mcpField
M
migrating-to-tuist-generated-projects

migrating-to-tuist-generated-projects

github.com/tuist开发35502 次安装31 周前更新
代码仓库

关于 migrating-to-tuist-generated-projects

此技能指导开发者将现有 Xcode 项目迁移为 Tuist 生成的项目，并检查目标、设置、依赖项及运行行为。流程涵盖清点配置、生成工作区、构建和模拟器验证。

主要功能

  1. 01迁移前构建与运行检查
  2. 02目标和设置清点
  3. 03配置 Tuist 清单
  4. 04映射依赖项与资源
  5. 05迭代排查构建问题
  6. 06模拟器启动验证

适用场景

  1. 01将应用从 Xcode 项目迁移
  2. 02迁移扩展和测试目标
  3. 03诊断生成项目的构建错误

安装

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

$npx skills add https://github.com/tuist/agent-skills --skill migrating-to-tuist-generated-projects

安装后在 Claude Code 中输入/migrating-to-tuist-generated-projects确认已加载。

详细介绍

迁移到 Tuist 生成的项目

快速开始

  1. 使用 xcodebuild 对应用进行基线构建并运行。
  2. 梳理目标、构建设置和外部依赖项。
  3. 创建 Tuist.swift、Project.swift 和 Tuist/Package.swift。
  4. 将设置提取到 .xcconfig 文件中，并在 Project.swift 中配置。
  5. 生成并构建：先运行 tuist generate --no-open，再运行 xcodebuild build。
  6. 修复构建问题，重新生成，并在模拟器上验证运行情况。

迁移前检查清单

  • 主应用方案以及所有扩展和测试方案
  • 目标列表（应用、扩展、测试、辅助工具）
  • 部署目标和 Bundle 标识符
  • Info.plist 位置和权利文件
  • 自定义构建设置（按目标和配置区分）
  • 外部依赖项（SPM、XCFramework、Local Package）
  • 构建脚本（SwiftGen、Sourcery、代码生成）
  • 运行时验证计划（模拟器目标和启动命令）

产出

  • Project.swift 和 Tuist.swift
  • 用于外部依赖项的 Tuist/Package.swift
  • .xcconfig 文件（可选，但建议使用）
  • 构建和运行时验证记录
  • 记录决策和修复内容的简短迁移日志

迁移工作流

1. 对项目进行基线验证

首先确认当前项目可以构建并运行。记录所用命令，以便用同样的方式验证生成的工作区。

xcodebuild build \
  -project App.xcodeproj \
  -scheme App \
  -configuration Debug \
  -destination "generic/platform=iOS Simulator" \
  -derivedDataPath DerivedDataBaseline
2. 梳理目标和设置

列出每个目标及其作用。如果构建设置较多，或由多个目标共用，请将其提取到 .xcconfig 文件中。保持部署目标和 Bundle 标识符与原项目一致，以免出现意外的运行时问题。

3. 添加 Tuist 清单

创建清单，并保持精简，尽量贴近现有项目。

  • Tuist.swift：启用所需的生成选项，并明确列出。
  • Project.swift：定义目标、源文件、资源、脚本和依赖项。
  • Tuist/Package.swift：列出外部依赖项并映射产品类型。

使用 .external 引用第三方依赖项，以保持依赖关系图一致。

4. 谨慎处理源文件和资源

这一环节务必仔细。小错误往往会导致后续出现大问题。

  • .intentdefinition 文件应放在 sources 中，而非 resources。
  • .xcstrings 应继续作为主要本地化来源。避免从重叠的 glob 中重复包含 .strings 或 .stringsdict。
  • 对 Settings.bundle 等 Bundle 使用 .folderReference。
  • 如果缺少资源 Bundle，请确保包目标声明了 .process("Resources")。
5. 生成并构建
tuist install
tuist generate --no-open
xcodebuild build \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Debug \
  -destination "generic/platform=iOS Simulator" \
  -derivedDataPath DerivedDataTuist
6. 逐步解决构建问题

你可能需要进行以下常见修复：

  • 缺少 SDK 框架：添加 .sdk(name: ..., type: .framework)。
  • SPM 资源 Bundle：检查 .process("Resources") 和 Bundle.module 的用法。
  • 文件系统同步组：避免排除过多目录；如果某种类型消失，请对照 pbx 检查。
  • 无效的 Bundle 标识符：使用 PackageSettings 覆盖，或将本地包纳入项目。
  • 生成的源文件：确保代码生成工具（SwiftGen/Sourcery）的输出已纳入构建。
7. 验证运行情况

仅构建成功还不够；请在模拟器上启动应用。

xcrun simctl boot "iPhone 17 Pro"
xcrun simctl install booted DerivedDataTuist/Build/Products/Debug-iphonesimulator/App.app
xcrun simctl launch booted com.example.app

常见失败模式

  • 找不到类型：某个源文件或整个目录被意外排除。
  • Copy Bundle Resources 错误：Swift 文件被当作资源处理；请修正资源 glob。
  • 本地化冲突：.xcstrings 与 .strings glob 冲突。
  • 未定义符号：缺少 SDK 框架或依赖产品。
  • 启动时出现无法识别的选择器：静态框架中的 ObjC 分类被剥离。将 -ObjC 添加到 OTHER_LDFLAGS，或对定义该分类的库使用 -force_load。
  • 启动时运行崩溃：Bundle ID 不匹配、缺少权利文件，或资源配置错误。

需要记录的迁移说明

  • Project.swift 中有哪些更改，以及更改原因
  • 任何排除项或覆盖项（及其原因）
  • 依赖项补丁或本地供应商代码
  • 用于验证的准确构建和运行命令

完成检查清单

  • 生成的工作区可顺利构建
  • App 在模拟器上启动后不会立即崩溃
  • 所有目标和扩展均可构建
  • 依赖项通过 .external 接入
  • 设置与原始 Xcode 项目保持一致

评论

支持 Markdown