当 SPM 依赖/插件/模块变体拖慢 Xcode 构建时…

怀疑 Swift Package Manager 包结构、插件或依赖配置导致 Xcode 清洁/增量构建变慢时，按证据收集、验证、报告流程分析并给出建议。

适用场景

解决思路

1. 把包分析先当作证据收集，而不是必须替换依赖。
2. 把包图问题与工程设置问题分开分析。
3. 未经明确批准，不要重写 Package manifest 或依赖源。
4. 检查 `Package.swift` 和 `Package.resolved`。
5. 检查本地包与远程包。
6. 检查 package plugin 和 build-tool 的使用。
7. 检查 binary target 占用。
8. 检查依赖分层、重复导入和潜在循环依赖。
9. 检查构建日志或时间摘要中与包相关的工作。
10. 在把任何本地包纳入建议前，先验证它确实属于项目依赖图；`Vendor/` 目录可能包含未链接到任何 target 的包。
11. 检查 `project.pbxproj` 中的 `XCLocalSwiftPackageReference` 条目，确认其引用了该包路径。
12. 检查 `XCSwiftPackageProductDependency` 条目，确认该包的产品已链接到至少一个 target。
13. 如果本地包存在于磁盘但未被项目引用，不要把它纳入构建时间建议。
14. 当建议为分支跟踪依赖固定版本时，先用辅助脚本一次性扫描所有分支固定依赖：`python3 scripts/check_spm_pins.py --project App.xcodeproj`。
15. 该脚本会对每个分支固定包检查 `git ls-remote --tags`，并报告哪些包有可用 tag 可用于固定。
16. 如果没有 tag，建议固定到具体 commit revision hash 以保证确定性。
17. 记录哪些包是因为上游没有 tag 而固定到分支，哪些包明明有 tag 却有意跟踪分支。
18. 分析 package graph 形状，以及变更会触发多少下游工作。
19. 分析本地开发与 CI 中的 plugin 开销。
20. 分析清洁环境中出现的 checkout 或 fetch 成本信号。
21. 分析配置漂移导致的重复模块构建。
22. 分析共享依赖的 package target 使用不同宏或选项带来的风险。
23. 分析依赖方向违规：功能模块互相依赖，而不是依赖共享下层。
24. 分析模块间循环依赖，并把共享契约抽取到 protocol module。
25. 分析超大模块（200+ 文件）扩大增量重建范围的问题。
26. 分析使用 `@_exported import` 的 umbrella modules 造成的隐藏依赖链。
27. 分析缺少 interface/implementation 分离而阻碍构建并行的问题。
28. 分析 test targets 依赖 app target 而不是依赖被测模块的问题。
29. 分析 Swift macro 重建级联：大量使用 Swift macros（如 TCA、基于 swift-syntax 的库）时，微小源码改动可能因宏展开使下游模块失效并接近全量重建。
30. 分析在没有预构建 binary 时 `swift-syntax` 按全架构构建，从而增加显著 clean-build 开销的问题。
31. 分析多平台构建倍增：增加第二平台 target（如 watchOS）可能使共享 SPM 包构建多次（如 iOS arm64、iOS x86_64、watchOS arm64），使 `SwiftCompile`、`SwiftEmitModule`、`ScanDependencies` 任务倍增。
32. 理解从 monolithic target 迁移到 modular multi-target SDK（例如用一个 umbrella library 替换为独立的 Core、RUM、Logs、Trace 模块）并不会自动减少构建时间。
33. 模块化 target 会增加 `SwiftCompile`、`SwiftEmitModule`、`ScanDependencies` 任务数量，因为每个 target 必须独立编译、扫描并 emit module。
34. 构建时间权衡取决于项目的并行余量以及实际需要多少个模块化 target。
35. 比较迁移前后的总 `SwiftCompile` 任务数。
36. 在推荐迁移以提升构建速度前，对两种配置做基准测试。
37. 如果动机是减少 API surface（只导入用到的部分），注明构建时间可能持平或增加，而 import hygiene 会改善。
38. 仅当项目当前编译了 monolithic SDK 中大量未使用部分，且模块化替代允许完全跳过这些未使用部分时，才为构建速度推荐模块化 SDK 迁移。
39. 当同一模块在 timing output 中多次出现时，调查是否因不同 package 或 target 选项强制产生额外 module variants。
40. 统一的 options 往往比削减少量源代码更重要。
41. 报告每条发现时，包含 evidence。
42. 报告每条发现时，包含 affected package 或 plugin。
43. 报告每条发现时，包含可能影响 clean-build 还是 incremental-build。
44. 报告每条发现时，包含相关的 CI 影响。
45. 报告每条发现时，包含 estimated impact。
46. 报告每条发现时，包含 approval requirement。
47. 如果主要问题与包无关，转交给 `xcode-project-analyzer` 或 `xcode-compilation-analyzer`：阅读目标技能的 SKILL.md，并在同一项目上下文应用其工作流。
48. 详细审计清单参见 `references/spm-analysis-checks.md`。
49. 共享建议结构参见 `references/recommendation-format.md`。
50. 来源引用参见 `references/build-optimization-sources.md`。

适用边界 · 注意事项

• 包、插件或依赖图并非主要瓶颈时，不要继续用本技能分析，应转交给 `xcode-project-analyzer` 或 `xcode-compilation-analyzer`。
• 没有明确批准时，不要重写 Package manifest 或依赖源。
• 如果动机只是减少 API surface 而不是构建速度，不要承诺模块化 SDK 迁移一定能提速。