Xcode 项目构建慢或增量构建异常时…

适用于对 Xcode 工程做项目级和目标级构建性能审计，排查慢增量构建、scheme 依赖、build settings、Run Script、并行化与模块配置等问题。

适用场景

解决思路

1. 默认以“给出建议”为先，不直接修改。
2. 在更改项目文件、scheme 或 build settings 之前，必须获得明确批准。
3. 优先使用可度量证据：Build Timing Summary、构建日志或项目配置证据。
4. 区分仅 Debug 构建的痛点和仅 Release 构建的痛点。
5. 审查 scheme 构建顺序和目标依赖。
6. 对照 references/build-settings-best-practices.md 审查 Debug 与 Release build settings。
7. 审查 Run Script phases 和 dependency-analysis 设置。
8. 审查 Derived Data 频繁变化或明显会使缓存失效的自定义步骤。
9. 寻找可并行化的机会。
10. 审查显式 module dependency 设置和 module-map 就绪情况。
11. 检查 Build Timing Summary 中 “Planning Swift module” 时间；若其主导增量构建，怀疑输入被意外修改或 macro 相关失效。
12. 检查 asset catalog 编译时间，尤其是包含大型或大量 catalog 的 target。
13. 检查 Build Timing Summary 中 ExtractAppIntentsMetadata 时间；若耗时显著，记录为 xcode-behavior，报告成本和影响，但除非有明确 Apple 指南，不要建议仓库本地优化。
14. 检查零改动构建开销；若 no-op rebuild 超过几秒，调查固定成本阶段，如 script execution、codesign、validation、CopySwiftLibs。
15. 检查 CocoaPods 使用；若存在 Podfile 或 Pods.xcodeproj，说明 CocoaPods 已弃用，建议迁移到 SPM，且不要尝试 CocoaPods 特定优化，见 references/project-audit-checks.md。
16. 使用 Task Backtraces（Xcode 16.4+：Scheme Editor > Build > Build Debugging）诊断增量构建中任务意外重跑的原因。
17. 每次项目审计都包含 build settings checklist，将项目 Debug 和 Release 配置与 references/build-settings-best-practices.md 推荐值对比。
18. 使用 [x]/[ ] 对勾/叉号展示 build settings checklist 结果。
19. 范围严格限定为构建性能；不要标记语言迁移类设置，如 SWIFT_STRICT_CONCURRENCY 或 SWIFT_UPCOMING_FEATURE_*。
20. 审查 target dependencies 是否准确、无缺失、无膨胀。
21. 审查 schemes 是否按 Dependency Order 构建。
22. 审查 Run Scripts 是否声明 inputs 和 outputs。
23. 当脚本有很多 inputs 或 outputs 时，审查是否使用 .xcfilelist 文件。
24. 审查在自定义 frameworks 或 libraries 应暴露 module maps 的地方是否启用 DEFINES_MODULE。
25. 审查 headers 是否足够自包含以用于 module-map。
26. 审查对应共享 modules 的 targets 的显式 module dependency 设置是否一致。
27. 跳过仅在 Release 有意义的 Debug 期脚本。
28. 为脚本补充缺失的 guards 或 dependency-analysis metadata。
29. 移除 schemes 中意外的串行瓶颈。
30. 对齐会导致不必要 module variants 的 build settings。
31. 修复过时项目结构，避免其强制更大范围重构建。
32. 识别会 touch 文件时间戳但内容未变的 linters 或 formatters，它们会静默使构建输入失效并迫使 module replanning。
33. 将大型 asset catalogs 拆分为跨 targets 的独立 resource bundles，以并行编译。
34. 使用 Task Backtraces 精确定位触发不必要增量工作的确切输入变更。
35. 对每个问题报告 evidence。
36. 对每个问题报告 likely scope。
37. 说明每个问题影响 clean builds、incremental builds 还是两者。
38. 给出每个问题的 estimated impact。
39. 给出每个问题的 approval requirement。
40. 若证据指向 package graph 或 build plugins，阅读 ../spm-build-analysis/SKILL.md 并按其工作流在相同项目上下文交接处理。
41. 查阅 references/project-audit-checks.md 获取详细审计清单。
42. 查阅 references/build-settings-best-practices.md 获取 build settings 最佳实践。
43. 查阅 references/recommendation-format.md 获取共享建议结构。
44. 查阅 references/build-optimization-sources.md 获取 Apple 对齐的来源摘要。

适用边界 · 注意事项

• 不要用于只能通过源代码修改解决的构建低效问题；本技能针对 project- and target-level 构建低效。
• 证据指向 package graph 或 build plugins 时，不要继续用本技能深入，改交给 spm-build-analysis。
• 不要标记语言迁移类设置，如 SWIFT_STRICT_CONCURRENCY、SWIFT_UPCOMING_FEATURE_*；本技能只关注构建性能。