AI Skills
xcode-project-setup

xcode-project-setup

热门

安全地修改 Xcode 项目文件 (.pbxproj)，添加 Swift Package 并链接文件。当 iOS 项目需要安装依赖（如 Firebase、Alamofire）时使用此技能。

357Star
71Fork
更新于 2026/6/21
获取 Skill源代码

相关 Skills

apple-hig8.4万i18n8.1万paperclip-create-agent7.5万
SKILL.md
readonly只读
name
xcode-project-setup
description

安全地修改 Xcode 项目文件 (.pbxproj)，添加 Swift Package 并链接文件。当 iOS 项目需要安装依赖（如 Firebase、Alamofire）时使用此技能。

Xcode 项目设置

⛔️ 关键规则与环境检查

在执行任何 Xcode 设置或文件操作之前，必须遵守以下规则。违反规则将产生高额费用。

1. 禁止使用 Ruby

严格禁止使用 Ruby、Rails 或任何 Ruby gem（包括 xcodeproj gem）。在任何情况下都不得编写或执行 Ruby 脚本。

2. 现代 Xcode 文件夹同步

现代 Xcode 项目支持文件夹同步。添加新的源代码（.swift）或资源文件时，只需将它们写入磁盘上的正确目录即可。它们将自动包含在 Xcode 项目中。切勿手动修改 .pbxproj 文件来添加文件。

3. 允许的脚本语言

如果必须编写脚本来操作项目环境（例如，配置超出提供的 xcode_spm_setup 脚本范围的 SPM 包），必须使用 Swift。仅当 Swift 完全不可行时，作为最后手段，才可使用 Node.js 或 TypeScript。

4. 工具链验证

由于此技能完全依赖原生 Swift 脚本，必须验证环境：

  • 在继续之前运行 swift --version。
  • 如果找不到 Swift 命令，必须停止并建议用户安装 Swift 工具链（例如，在 macOS 上通过 xcode-select --install），或询问是否可以尝试为用户安装。不要在没有 Swift 的情况下继续。

5. 静态框架（Firebase）的强制链接器标志

当设置严重依赖内部 Objective-C 类别和 +load 方法的 SPM 依赖项（如 Firebase iOS SDK 套件）时，如果静态链接，Apple 链接器会积极剥离这些方法。

这会导致运行时致命崩溃（例如 FirebaseAuth/Auth.swift:167: Fatal error: Unexpectedly found nil）。

提供的 xcode_spm_setup Swift 脚本在添加 Firebase 产品时会自动将 -ObjC 标志注入到 OTHER_LDFLAGS 中。 但如果遇到问题，仍应验证该标志是否存在于构建设置中。

  • 添加 Firebase 依赖时未包含此标志是严重错误。

空目录工作流程

如果要求构建 iOS 应用或配置 Xcode 依赖，但不存在 .xcodeproj 或 .xcworkspace，必须要求用户先创建项目：

"在此目录中未找到 Xcode 项目。请手动创建一个空的 Xcode 项目，并在准备好继续时告知我。"

等待用户确认已通过 Xcode 创建了 .xcodeproj，然后继续执行下面的标准 Xcode 工作流程。

标准 Xcode 工作流程

不要使用原始文本解析、sed 或 Ruby 脚本直接修改 .pbxproj 文件。

而是执行此技能附带的 Swift 配置包（scripts/xcode_spm_setup），以安全地安装 SPM 包并链接可选配置文件（如 GoogleService-Info.plist）。

关键：始终使用最新 SDK 版本

为确保访问最新功能和安全修复，始终使用最新版本的 Firebase iOS SDK。在 https://github.com/firebase/firebase-ios-sdk/releases 查看最新版本。

  • 在命令中使用最新版本号（例如 11.x.y），而不是硬编码的占位符。

理解脚本的操作

向 Xcode 项目添加 Swift Package 时，必须执行两个不同的步骤：

  1. 添加包仓库依赖（例如 https://github.com/Alamofire/Alamofire）。
  2. 选择目标（例如 MyApp），导航到 General > Frameworks, Libraries, and Embedded Content，点击 + 按钮显式链接特定产品模块（例如 Alamofire）。

提供的 xcode_spm_setup Swift 脚本会自动处理这两个步骤。 通过将模块列表作为参数传递，它安全地注入包依赖，并自动将这些模块连接到主目标的 Frameworks 构建阶段。无需手动链接。

用法

  1. 定位包路径： 找到此技能 scripts/xcode_spm_setup 目录在磁盘上的绝对路径。
  2. 执行： 使用以下签名运行原生 swift run 命令：
swift run --package-path <技能路径>/scripts/xcode_spm_setup xcode_spm_setup <项目路径.xcodeproj> <仓库URL> <版本要求> [--plist <可选/配置.plist路径>] <产品1> [产品2 ...]

示例 1：通用包（例如 Alamofire）

向标准 Xcode 项目添加 Alamofire。注意没有 --plist 标志。

swift run --package-path /Users/foo/.agents/skills/xcode-project-setup/scripts/xcode_spm_setup xcode_spm_setup MyApp.xcodeproj https://github.com/Alamofire/Alamofire 5.8.1 Alamofire

示例 2：Firebase（需要 Plist）

添加 Firebase 并自动将 GoogleService-Info.plist 链接到资源构建阶段。
注意：将 11.0.0 替换为 发布页面 上的实际最新版本。

swift run --package-path /Users/foo/.agents/skills/xcode-project-setup/scripts/xcode_spm_setup xcode_spm_setup MyApp.xcodeproj https://github.com/firebase/firebase-ios-sdk 11.0.0 --plist MyApp/GoogleService-Info.plist FirebaseCore FirebaseAuth FirebaseFirestore

注意：该脚本是幂等的。它会自动跳过链接项目中已存在的文件或包。