debug-generated-project

调试 Tuist 项目问题

快速开始

1. 请用户描述问题和项目设置（targets、依赖项、配置、平台）。
2. 使用复现项目运行 mise exec tuist@latest -- tuist generate，确认最新版本中是否仍存在问题。
3. 如果确认问题仍存在，克隆 Tuist 仓库并从源代码构建，以便使用 main 分支进行测试。
4. 进行分类处理：修复 bug 并提交 PR、指出配置错误，或建议用户提交包含复现步骤的问题报告。

第 1 步：收集背景信息

请用户提供：

• 运行的命令（例如 tuist generate）
• 错误消息或意外行为
• 问题发生的时间：生成时、编译时还是运行时（应用启动时或启动后）
• 项目结构：targets、平台、依赖项（SwiftPM、XCFrameworks、本地包）
• Project.swift 和 Tuist.swift 的内容（或相关片段）
• Tuist 版本（tuist version）

用户对“何时发生”的回答决定了验证策略：

• 生成时：问题可能是 Tuist bug，也可能是项目配置错误。使用 tuist generate 复现。
• 编译时：生成的项目可能存在错误的构建设置、缺少源文件或依赖连接错误。生成项目后，使用 xcodebuild build 复现。
• 运行时：应用可以构建，但启动或使用过程中会崩溃或行为异常。尝试在模拟器上安装并启动应用以复现。

第 2 步：使用最新版本复现

调查源代码之前，先确认最新版本中是否已经修复了该问题。

设置临时复现项目

REPRO_DIR=$(mktemp -d)
cd "$REPRO_DIR"

创建最简的 Tuist.swift、Project.swift 和源文件，以复现用户的场景。在仍能触发问题的前提下，尽可能精简项目。

使用最新 Tuist 版本运行生成命令

mise exec tuist@latest -- tuist generate --no-open --path "$REPRO_DIR"

如果问题涉及依赖项，请先安装依赖项：

mise exec tuist@latest -- tuist install --path "$REPRO_DIR"

检查结果

• 如果生成成功且问题已消失，请告知用户更新到最新版本。
• 如果问题仍然存在，请继续执行第 3 步。

第 3 步：从源代码构建 Tuist

克隆仓库，并从源代码构建 tuist 可执行文件和 ProjectDescription 库，以便使用 main 分支上的最新代码进行测试。

TUIST_SRC=$(mktemp -d)
git clone --depth 1 https://github.com/tuist/tuist.git "$TUIST_SRC"
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry

构建好的二进制文件位于 .build/debug/tuist。使用它测试复现项目：

"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"

如果问题已在 main 分支修复

告知用户该修复已合并到 main，但尚未发布；告诉用户该修复会包含在下一个版本中，并在能够确认相关提交时提供链接。

如果问题在 main 分支中仍然存在

继续执行第 4 步。

第 4 步：对问题进行分类处理

调查 Tuist 源代码，了解问题发生的原因。

结果 A：这是一个 bug

1. 在源代码中找出根本原因。
2. 应用修复。
3. 通过重新构建并使用复现项目运行来验证：

   cd "$TUIST_SRC"
   swift build --product tuist --product ProjectDescription --replace-scm-with-registry
   "$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"
   

4. 将复现项目打包为 ZIP 文件，并附在 PR 中：

   cd "$REPRO_DIR" && cd ..
   zip -r reproduction.zip "$(basename "$REPRO_DIR")" -x '*.xcodeproj/*' -x '*.xcworkspace/*' -x 'Derived/*' -x '.build/*'
   

5. 在 Tuist 仓库中提交 PR，包含：
   • 修复内容
   • 附加或提交为 fixture 的 ZIP 格式复现项目
   • 对根本原因以及如何验证修复的清晰说明

结果 B：这是配置错误

告知用户哪里配置有误以及如何修复。常见的配置错误包括：

• 使用外部依赖项时，在运行 tuist generate 前未运行 tuist install
• 源文件或资源 glob 配置错误，导致文件被排除或重复包含
• 项目与外部依赖项之间的构建配置不匹配
• 依赖项的产品类型错误（静态或动态）
• Objective-C 依赖项缺少 -ObjC 链接器标志
• 将 sources 和 resources glob 与 buildableFolders 一起使用

提供修正后的清单代码片段，方便用户直接应用修复。

结果 C：不明确或需要团队介入

如果无法确定这是 Bug 还是配置错误，建议用户：

1. 在 https://github.com/tuist/tuist/issues 上创建 GitHub issue，并附上：
   • 复现项目（压缩包）
   • 错误输出
   • Tuist 版本和环境详情

总结你调查的内容以及排除的可能性，避免用户重复进行问题排查。

构建验证

测试修复时，务必验证完整流程：

# Build the patched tuist
cd "$TUIST_SRC"
swift build --product tuist --product ProjectDescription --replace-scm-with-registry

# Install dependencies if needed
"$TUIST_SRC/.build/debug/tuist" install --path "$REPRO_DIR"

# Generate the project
"$TUIST_SRC/.build/debug/tuist" generate --no-open --path "$REPRO_DIR"

# Build the generated project
xcodebuild build \
  -workspace "$REPRO_DIR"/*.xcworkspace \
  -scheme <scheme> \
  -destination "platform=iOS Simulator,name=iPhone 16 Pro"

运行时验证

当用户报告运行时问题（启动时崩溃、运行时缺少资源、Bundle 结构错误或行为异常）时，不能只进行构建，还必须在模拟器上实际启动应用。

启动应用并监控崩溃

# Boot a simulator
xcrun simctl boot "iPhone 16 Pro" 2>/dev/null || true

# Build for the simulator
xcodebuild build \
  -workspace "$REPRO_DIR"/*.xcworkspace \
  -scheme <scheme> \
  -destination "platform=iOS Simulator,name=iPhone 16 Pro" \
  -derivedDataPath "$REPRO_DIR/DerivedData"

# Install the app
xcrun simctl install booted "$REPRO_DIR/DerivedData/Build/Products/Debug-iphonesimulator/<AppName>.app"

# Launch and monitor — this will print crash info if the app terminates abnormally
xcrun simctl launch --console-pty booted <bundle-identifier>

--console-pty 标志会输出应用的 stdout/stderr，以便直接查看日志和崩溃输出。请留意：

• 启动时立即崩溃：通常是缺少框架、Bundle ID 错误、缺少权利，或 ObjC 类别被剥离（缺少 -ObjC 链接器标志）
• 几秒后崩溃：通常是缺少资源（图像、storyboard、XIB、资源目录），或 Bundle 结构不匹配
• 未崩溃但运行时行为异常：资源路径错误、缺少本地化文件，或 Info.plist 值不正确

检查崩溃日志

如果应用崩溃但控制台没有提供有用的输出，请获取崩溃日志：

# List recent crash logs for the app
find ~/Library/Logs/DiagnosticReports -name "<AppName>*" -newer "$REPRO_DIR" -print

阅读崩溃日志，确定发生崩溃的线程和出错的符号。

完成检查清单

• 已从用户处收集足够的信息，以复现问题
• 已确定问题发生在生成时、编译时还是运行时
• 已确认最新版本中是否存在该问题
• 已使用从源代码构建的 Tuist（main 分支）进行测试
• 如果是运行时问题：已在模拟器上启动应用，并验证崩溃或异常行为
• 已将问题归类为 Bug、配置错误或不明确
• 如果是 Bug：已应用修复、完成验证，并附上复现项目创建 PR
• 如果是配置错误：已向用户提供修正后的 manifest
• 如果问题不明确：已向用户提供总结并建议后续步骤