mcpField
X
xcode-project-setup

xcode-project-setup

github.com/firebase开发491132.0k 次安装1 天前更新
代码仓库

关于 xcode-project-setup

用于在现有 Xcode 项目中配置 Swift Package Manager 依赖的技能，通过附带的 Swift 脚本完成操作。它可添加依赖并链接产品、纳入可选 plist，以及处理 Firebase 链接器设置，避免直接编辑项目文件。

主要功能

  1. 01添加 SPM 包依赖
  2. 02将产品链接到项目目标
  3. 03纳入可选 plist 文件
  4. 04设置 Firebase 的 -ObjC 链接标志
  5. 05跳过已配置的依赖

适用场景

  1. 01为 Xcode 项目添加包
  2. 02链接 Firebase 产品并纳入 plist
  3. 03无需直接编辑 .pbxproj 配置 SPM

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/firebase/agent-skills --skill xcode-project-setup

安装后在 Claude Code 中输入/xcode-project-setup确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

scripts/xcode_spm_setup/
.gitignore
Package.resolved
Package.swift
scripts/xcode_spm_setup/Sources/
main.swift

详细介绍

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），而不要使用硬编码的占位符。
了解脚本的操作

将 Swift Package 添加到 Xcode 项目时，必须完成两个不同的步骤：

  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 <PATH_TO_SKILL>/scripts/xcode_spm_setup xcode_spm_setup <ProjectPath.xcodeproj> <RepoURL> <VersionRequirement> [--plist <Optional/Path/To/Config.plist>] <Product1> [Product2 ...]
示例 1：通用软件包（例如，Alamofire）

将 Alamofire 添加到标准 Xcode 项目。请注意，这里没有 --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

注意：该脚本具有幂等性。如果文件或软件包已存在于项目中，它会自动跳过链接。

评论

支持 Markdown