返回技能市场
开发运维 安全

xcode-project-setup

@admin/xcode-project-setup

Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).

admin 热度 446v0.0.1

Xcode 项目设置

⛔️ 关键规则与环境检查

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

1. 禁止 Ruby 的铁律

你严禁使用 Ruby、Rails 或任何 Ruby gems（包括 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 categories 和 +load 方法的 SPM 依赖（例如 Firebase iOS SDK 套件）时，如果静态链接，Apple 链接器会激进地剥离这些方法。

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

提供的 xcode_spm_setup Swift 脚本在添加 Firebase 产品时会自动向 OTHER_LDFLAGS 注入 -ObjC 标志。 然而，如果遇到问题，你仍应验证构建设置中存在它。

  • 添加 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. 添加包仓库依赖（例如，

    2. https://github.com/Alamofire/Alamofire）。

  2. 选择目标（例如 MyApp），导航到 General > Frameworks, Libraries, and Embedded Content，并按下 + 按钮以显式链接特定产品模块（例如 Alamofire）。

提供的 xcode_spm_setup Swift 脚本会自动为你处理这两个步骤。 通过传递模块列表作为参数，它会安全注入包依赖，并自动将这些模块连接到主目标的 Frameworks build phase。你不需要进行任何手动链接。

使用

  1. 定位包路径： 找到此技能的

    2. scripts/xcode_spm_setup 目录在磁盘上的绝对路径。

  2. 执行： 使用下面的签名运行原生 swift run 命令：
swift run --package-path <PATH_TO_SKILL>/scripts/xcode_spm_setup xcode_spm_setup <ProjectPath.xcodeproj> <RepoURL> <VersionRequirement> [--plist <Optional/Path/To/Config.plist>] <Product1> [Product2 ...]

示例 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 链接到 resources build phase。*注意：将 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

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

qianwen skills install @admin/xcode-project-setup