返回

解决iOS+WatchKit+WidgetKit构建错误: 缺少AppIcon

IOS

iOS+WatchKit+WidgetKit 应用构建错误：资源目录缺少内容

在通过 xcodebuild 构建包含 iOS、WatchKit 和 WidgetKit 的应用时，有时会出现类似 "The stickers icon set or app icon set named "AppIcon" did not have any applicable content" 的错误。 此问题通常阻碍构建过程，尤其是在自动化构建环境中（如 GitHub Actions）中。

问题分析

这个错误的根源在于 xcodebuild 构建过程中的资源处理阶段。具体而言，CompileAssetCatalog 工具在查找必要的应用图标集（AppIcon set）时，没有找到适用的内容。这可能是因为：

  1. 资源目录（Asset Catalogs）配置不正确 ： Assets.xcassets 中的应用图标集未正确配置或丢失了必要的尺寸和类型。
  2. 构建目标设置错误 : 构建配置可能没有正确的指定应该使用的资源文件。
  3. 缓存问题 : 之前构建过程中的缓存数据可能导致了问题。

这些原因会导致 CompileAssetCatalog 任务失败，中断构建过程。尤其当构建环境（例如CI）和本地开发环境配置存在差异时更容易发生。

解决方案

以下是一些解决此问题的方案，可根据情况选择合适的方案执行。

方案一：检查资源目录设置

这是最常见的错误源。确保Assets.xcassets 文件中包含所有必需的应用程序图标，并且这些图标都配置正确。

  • 步骤：

    1. 在 Xcode 中打开项目。
    2. 导航到 Assets.xcassets 文件。
    3. 选择 AppIcon 资源集合。
    4. 检查是否所有必要的图标尺寸和设备都已配置。对于包含 WatchKit 或 WidgetKit 的项目，不仅要关注 iOS 的图标，还要注意其他扩展目标（target）所需要的图标，它们通常都放置在同一个资源文件中，使用不同的图标集，需要独立配置。
    5. 确认是否有遗漏的设备尺寸图标，或者图标格式（PNG/JPEG）。确保没有额外的、空的图标占用着位置，以及它们是否正确引用了你的实际图片资源。
    6. 确保每一个目标 (iOS, watchOS, widget extension 等等) 都有其正确的 AppIcon 配置。确保每一个目标中的配置都已经勾选上对应 Target。
    7. 如果出现任何遗漏或错误，请添加或修改相应的图标，或者检查它们正确的对应到 target 的关系。
    8. 清理构建文件夹 ( Cmd + Shift + K ) 再次尝试构建，验证修复。

  • 原理 ：此步骤直接解决了 AppIcon 配置不足的问题。确保所有的 AppIcon 图标资源存在且正确关联，以确保 CompileAssetCatalog 任务能找到所需的资源并顺利构建。

方案二：清理 Xcode 构建缓存

Xcode 的缓存有时会导致奇怪的构建错误，清理缓存能够解决部分问题。

  • 步骤 ：

    1. 关闭 Xcode 项目。
    2. 在终端中，导航到您的项目目录。
    3. 执行命令: rm -rf ~/Library/Developer/Xcode/DerivedData/ 来删除 Xcode 的缓存文件夹
    4. 打开 Xcode，重新尝试构建。
    • 如果使用cocoapods 还需要 执行 pod deintegrate , 然后再次执行pod install，重新生成 project workspace.

  • 原理 ：清除缓存可以消除过时的或损坏的构建信息，从而允许 Xcode 从头开始重新构建，有可能解决由于构建数据错误导致的 AppIcon 问题。

方案三：检查构建目标设置

错误的构建目标设置可能会导致资源没有被正确引入项目。确保在各个 target (例如：iOS App, Watch Extension, Widget Extension ) 的 Build Settings 里正确配置。

  • 步骤:

    1. 选择对应的target
    2. 选择 "Build Settings" 标签.
    3. 在搜索框中，输入 "Asset Catalog Compiler" 。 确保该编译选项已经正确引用你项目中的 asset catalog。或者使用资源路径绝对地址（从 / 开始）。
    4. 再次查看 "Asset Catalog Compiler Options",确保 "App Icon Sets" 是否指定了正确的名字，该名字应该和你 xcassest 里 iconset 的名字保持一致，例如 AppIcon 。
    5. 仔细确认各个target之间的编译参数配置没有冲突。

  • 原理 ： 该操作确保所有构建配置正确的关联了资源，使得在执行 xcodebuild 指令的时候能定位到必要的资源。

方案四：针对 GitHub Actions 环境进行特殊配置

某些情况下，在 GitHub Actions 上构建时会出现与本地不同的构建行为，这通常与CI的环境配置差异有关，所以可能需要在CI构建步骤中采取特殊配置。

  • 步骤：

    1. 检查 workflow 文件，保证使用了正确的 SDK 和 iOS 模拟器环境。

    2. 考虑在构建前显式执行一次清理构建命令: xcodebuild -project “Project.xcodeproj” -scheme “${{ matrix.scheme }}” -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 14,OS=latest' clean 然后在执行正式的构建步骤.

    3. 确认所有依赖（特别是 Swift Packages 或 CocoaPods）在 GitHub Actions 环境中正确解析。如果使用了缓存，也需要清除 Actions Cache，或者考虑关闭cache观察构建情况。

    4. 如果资源路径有问题, 可以使用明确的资源文件路径代替相对路径。如

xcodebuild -project Project.xcodeproj
-scheme "Project"
-sdk iphonesimulator
-destination "platform=iOS Simulator,name=iPhone 14,OS=latest"
GCC_PRECOMPILE_PREFIX_HEADER=YES
ASSETCATALOG_COMPILER_APPICON_NAME=AppIcon
clean build
```

  • 原理 ：这些步骤旨在保证 GitHub Actions 环境中与本地构建环境尽可能一致。明确的配置能避免环境变量或环境差异导致的潜在构建问题。并且可以强制设置构建时的 asset 参数。

通过上述一个或者多个方案的尝试，大多数情况能够解决类似 “AppIcon” did not have any applicable content的问题，顺利进行项目的自动化构建。 在构建前执行一次清理命令是很好的习惯。 同时也要持续保持 Asset Catalog 内容的完整性，确保项目构建的稳定性。