xcode-compilation-analyzer

Xcode 编译分析器

当编译时间（而非一般项目配置）看起来是瓶颈时，使用此技能。

核心规则

• 从证据入手，最好是近期的 .build-benchmark/ 产物或原始计时摘要输出。
• 调查期间，优先使用仅分析的编译器标志，而非持久性项目修改。
• 根据预期的实际耗时为发现排序，而非累计编译时间。当编译任务高度并行化（编译类别时间总和远大于实际耗时中位数）时，请指出，修复单个热点可能提升并行效率，但不一定缩短构建等待时间。
• 当证据表明问题在于并行化任务，而非串行瓶颈时，将建议标为“减少编译器工作量（并行）”，而不是“缩短构建时间”。
• 未经开发者明确批准，不要修改源代码或构建设置。

检查内容

• 干净构建和增量构建的 Build Timing Summary 输出
• 运行时间较长的 CompileSwiftSources 或单文件编译任务
• SwiftEmitModule 时间——大型模块发生单行更改后，可能达到 60 秒以上；如果它在增量构建中占主导，说明模块可能过于庞大或宏过多
• Planning Swift module 时间——如果此类别在增量构建中占比异常高（每个模块最多 30 秒），则表明输入失效异常或宏相关的重建级联
• 以下临时运行方式：
  • -Xfrontend -warn-long-expression-type-checking=<ms>
  • -Xfrontend -warn-long-function-bodies=<ms>
• 用于深入调查的诊断标志：
  • -Xfrontend -debug-time-compilation——按文件统计编译时间，以便找出最慢的文件
  • -Xfrontend -debug-time-function-bodies——按函数统计编译时间（不过滤），可补充基于阈值的警告标志
  • -Xswiftc -driver-time-compilation——驱动程序级别的计时，用于分离驱动程序开销
  • -Xfrontend -stats-output-dir <path>——按编译单元输出详细的编译器统计信息（JSON），用于根因分析
• 会增加桥接工作量的 Swift 与 Objective-C 混合接口

分析工作流

1. 确定主要问题是整体编译量过大，还是少数极端热点。
2. 解析计时摘要类别，并按影响最大的编译项排序。
3. 运行诊断脚本，找出类型检查热点：

   python3 scripts/diagnose_compilation.py \
     --project App.xcodeproj \
     --scheme MyApp \
     --configuration Debug \
     --destination "platform=iOS Simulator,name=iPhone 16" \
     --threshold 100 \
     --output-dir .build-benchmark
   

   此脚本会列出超过毫秒阈值的函数和表达式，并按耗时排序。结合源代码检查诊断产物，优先关注开销最大的文件。
4. 将证据转化为具体的建议列表。
5. 将代码级建议与项目级或模块级建议分开。

Apple 衍生检查项

首先检查以下模式：

• 开销较大的表达式缺少显式类型信息
• 难以进行类型检查的复杂链式表达式或嵌套表达式
• 委托属性使用 AnyObject 类型，而非具体协议
• 过于庞大的 Objective-C 桥接头文件，或生成的 Swift-to-Objective-C 接口
• 头文件导入未使用框架限定，导致无法复用模块缓存
• 从未被子类化但缺少 final 的类
• 仅供内部使用的符号具有过宽的访问控制范围（public/open）
• 应拆分为子视图的单体 SwiftUI body 属性
• 缺少中间类型注解的长方法链或闭包

报告格式

对于每条建议，请包含：

• 观察到的证据
• 可能受影响的文件或模块
• 预期等待时间影响（例如：“预计可将干净构建时间缩短约 2 秒”或“减少并行编译工作，但不太可能缩短构建等待时间”）
• 置信度
• 应用前是否需要批准

如果证据表明问题出在项目配置，而非源代码，请阅读其 SKILL.md，并按照相同项目上下文应用 xcode-project-analyzer 的工作流进行交接。

首选策略

• 建议先通过构建命令临时注入标志，再考虑持久化修改构建设置。
• 优先将庞大的视图构建器、闭包或结果构建器表达式拆分为更小的类型化单元。
• 在显式导入和协议类型能够缩小编译器搜索范围时，建议采用它们。
• 当真正的问题在于混合语言边界，而非单纯的 Swift 语法时，应明确指出。

其他资源

• 详细的审计清单请参阅 references/code-compilation-checks.md
• 通用的建议结构请参阅 references/recommendation-format.md
• 源码引用请参阅 references/build-optimization-sources.md