xcode-build-fixer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Xcode Build Fixer

Xcode 构建修复工具

Use this skill to implement approved build optimization changes and verify them with a benchmark.

使用此工具来实施已获批的构建优化变更，并通过基准测试验证效果。

Core Rules

核心规则

Only apply changes that have explicit developer approval.
Apply one logical fix at a time so changes are reviewable and reversible.
Re-benchmark after applying changes to verify improvement.
Report exactly what changed, which files were touched, and the measured delta.
If a change produces no improvement or causes a regression, flag it immediately.

仅应用获得开发者明确批准的变更。
每次应用一个逻辑修复，确保变更可审查且可回滚。
应用变更后重新进行基准测试，验证改进效果。
准确报告变更内容、修改的文件以及测得的差异。
如果变更未带来改进或导致性能退化，立即标记该问题。

Inputs

输入要求

The fixer expects one of:

An approved optimization plan at
```
.build-benchmark/optimization-plan.md
```
with checked approval boxes.
An explicit developer instruction describing the fix to apply (e.g., "set
```
DEBUG_INFORMATION_FORMAT
```
to
```
dwarf
```
for Debug").

When working from an optimization plan, read the approval checklist and implement only the checked items.

修复工具需要以下其中一种输入：

位于
```
.build-benchmark/optimization-plan.md
```
的已获批优化计划，且其中的批准复选框已勾选。
明确的开发者指令，描述需要应用的修复（例如："将
```
DEBUG_INFORMATION_FORMAT
```
设置为
```
dwarf
```
以适配 Debug 模式"）。

基于优化计划工作时，请阅读批准清单，仅实施已勾选的项。

Fix Categories

修复类别

Build Settings

构建设置

Change

project.pbxproj

values to match the recommendations in build-settings-best-practices.md.

Typical fixes:

Set
```
DEBUG_INFORMATION_FORMAT = dwarf
```
for Debug
Set
```
SWIFT_COMPILATION_MODE = singlefile
```
for Debug
Enable
```
COMPILATION_CACHING = YES
```
Enable
```
EAGER_LINKING = YES
```
for Debug
Align cross-target settings to eliminate module variants

When editing

project.pbxproj

, locate the correct

buildSettings

block by matching the target name and configuration name. Verify the change with

xcodebuild -showBuildSettings

after applying.

修改

project.pbxproj

中的值，使其与 build-settings-best-practices.md 中的建议一致。

典型修复：

为 Debug 模式设置
```
DEBUG_INFORMATION_FORMAT = dwarf
```
为 Debug 模式设置
```
SWIFT_COMPILATION_MODE = singlefile
```
启用
```
COMPILATION_CACHING = YES
```
为 Debug 模式启用
```
EAGER_LINKING = YES
```
统一跨目标设置，消除模块变体

编辑

project.pbxproj

时，通过匹配目标名称和配置名称找到正确的

buildSettings

块。应用变更后，使用

xcodebuild -showBuildSettings

验证修改。

Script Phases

脚本阶段

Fix run script phases that waste time during incremental or debug builds.

Typical fixes:

Add input and output file declarations so Xcode can skip unchanged scripts.
Add configuration guards:
```
[[ "$CONFIGURATION" != "Release" ]] && exit 0
```
for release-only scripts.
Move input/output lists into
```
.xcfilelist
```
files when the list is long.
Enable
```
Based on dependency analysis
```
when inputs and outputs are declared.

修复在增量构建或调试构建中耗时的运行脚本阶段。

典型修复：

添加输入和输出文件声明，使Xcode可以跳过未变更的脚本。
添加配置防护：针对仅在Release模式运行的脚本，添加
```
[[ "$CONFIGURATION" != "Release" ]] && exit 0
```
。
当输入/输出列表较长时，将其移至
```
.xcfilelist
```
文件中。
声明输入和输出后，启用"基于依赖分析"。

Source-Level Compilation Fixes

源码级编译修复

Apply code changes that reduce type-checker and compiler overhead. See references/fix-patterns.md for before/after patterns.

Typical fixes:

Add explicit type annotations to complex expressions.
Break long chained or nested expressions into intermediate typed variables.
Mark classes
```
final
```
when they are not subclassed.
Tighten access control (
```
private
```
/
```
fileprivate
```
) for internal-only symbols.
Extract monolithic SwiftUI
```
body
```
properties into smaller composed subviews.
Replace deeply nested result-builder code with separate typed helpers.
Add explicit return types to closures passed to generic functions.

应用减少类型检查器和编译器开销的代码变更。具体的前后对比模式请参见 references/fix-patterns.md。

典型修复：

为复杂表达式添加显式类型注解。
将长链式或嵌套表达式拆分为带类型的中间变量。
当类不被子类化时，标记为
```
final
```
。
为仅内部使用的符号收紧访问控制（
```
private
```
/
```
fileprivate
```
）。
将庞大的SwiftUI
```
body
```
属性提取为更小的组合子视图。
用独立的类型化辅助代码替换深度嵌套的结果构建器代码。
为传递给泛型函数的闭包添加显式返回类型。

SPM Restructuring

SPM 重构

Restructure Swift packages to improve build parallelism and reduce rebuild scope.

Typical fixes:

Move shared types to a lower-layer module to eliminate circular or upward dependencies.
Split oversized modules (200+ files) by feature area.
Extract protocol definitions into lightweight interface modules.
Remove unnecessary
```
@_exported import
```
usage.
Align build options across targets that import the same packages to prevent module variant duplication.
Pin branch-tracked dependencies to tagged versions or commit hashes for deterministic resolution.

Before applying version pin changes:

Run
```
git ls-remote --tags <url>
```
to confirm tags exist. If the upstream has no tags, pin to a specific revision hash instead.
Verify the pinned version resolves successfully with
```
xcodebuild -resolvePackageDependencies
```
before proceeding.

重构Swift包以提升构建并行度并减少重构范围。

典型修复：

将共享类型移至下层模块，消除循环依赖或向上依赖。
按功能领域拆分过大的模块（200+文件）。
将协议定义提取为轻量级接口模块。
移除不必要的
```
@_exported import
```
用法。
对齐导入相同包的所有目标的构建设置，防止模块变体重复。
将跟踪分支的依赖固定到标记版本或提交哈希，以实现确定性解析。

应用版本固定变更前：

运行
```
git ls-remote --tags <url>
```
确认标签存在。如果上游没有标签，则固定到特定的修订哈希。
应用前使用
```
xcodebuild -resolvePackageDependencies
```
验证固定版本是否能成功解析。

Execution Workflow

执行流程

Read the approved optimization plan or developer instruction.
For each approved item, identify the exact files and locations to change.
Apply the change.
Verify the change compiles: run a quick
```
xcodebuild build
```
to confirm no errors were introduced.

After all approved changes are applied, re-benchmark using the same inputs from the original baseline:

bash

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

Compare post-change medians to the baseline and report deltas.

读取已获批的优化计划或开发者指令。
针对每个已获批的项，确定需要修改的具体文件和位置。
应用变更。
验证变更可编译：运行快速的
```
xcodebuild build
```
确认未引入错误。

应用所有已获批变更后，使用与原始基准测试相同的输入重新进行基准测试：

bash

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

将变更后的中位数与基准值进行比较，并报告差异。

Evaluating Regressions

退化评估

Not every slower number is a true regression. The fixer must evaluate the full picture before recommending a revert.

并非所有耗时增加的情况都是真正的性能退化。修复工具在建议回滚前必须全面评估整体情况。

Compilation caching trade-off

编译缓存权衡

A change like

COMPILATION_CACHING = YES

may make a standard clean build slightly slower (cache population overhead) while making cached clean builds significantly faster. Since cached clean builds reflect the realistic developer workflow (branch switching, pulling changes, Clean Build Folder with a warm cache), a slower standard clean build paired with a faster cached clean build is a net improvement, not a regression. The same logic applies to any change where the first-time cost is higher but subsequent builds benefit.

像

COMPILATION_CACHING = YES

这样的变更可能会使标准干净构建稍微变慢（缓存填充开销），但会使缓存后的干净构建显著加快。由于缓存后的干净构建更能反映真实的开发者工作流（分支切换、拉取变更、使用暖缓存执行Clean Build Folder），因此标准干净构建变慢但缓存后干净构建变快属于净改进，而非退化。同样的逻辑适用于首次成本较高但后续构建受益的任何变更。

Compare all build types

比较所有构建类型

Evaluate standard clean, cached clean (when available), and incremental builds together. A change is only a clear regression if it makes the metrics that matter to the developer's daily workflow worse. If only the cold-start clean build is slower but the developer rarely does truly cold builds, that may be acceptable.

同时评估标准干净构建、缓存干净构建（如果可用）和增量构建。只有当变更使开发者日常工作流中重要的指标变差时，才属于明确的退化。如果只有冷启动干净构建变慢，但开发者很少进行真正的冷构建，这种情况可能是可接受的。

Per-change vs. cumulative

单个变更与累积效果

A single change that regresses on its own may still be worth keeping if it enables a larger cumulative improvement (e.g., enabling compilation caching makes one build type slower but unlocks cache benefits for everything else).

单个变更本身可能导致退化，但如果它能带来更大的累积改进（例如，启用编译缓存使一种构建类型变慢，但解锁了所有其他构建的缓存优势），那么仍然值得保留。

Best-practice settings are not revert candidates

最佳实践设置不可回滚

Some build settings are Apple's recommended modern defaults. These should be applied and kept regardless of whether the immediate benchmark shows a measurable improvement. They are not speculative optimizations -- they align the project with Apple's toolchain direction and will compound in value over future Xcode releases. The fixer must never recommend reverting these settings based on a single benchmark result.

Best-practice settings that should always be kept once applied:

```
COMPILATION_CACHING = YES
```
-- Apple is actively investing in this; the cache improves with each Xcode release and compounds across real workflows
```
EAGER_LINKING = YES
```
(Debug) -- allows the linker to overlap with compilation
```
SWIFT_USE_INTEGRATED_DRIVER = YES
```
-- eliminates inter-process scheduling overhead
```
DEBUG_INFORMATION_FORMAT = dwarf
```
(Debug) -- avoids unnecessary dSYM generation
```
SWIFT_COMPILATION_MODE = singlefile
```
(Debug) -- incremental recompilation
```
ONLY_ACTIVE_ARCH = YES
```
(Debug) -- no reason to build all architectures locally

When reporting on these settings, use language like: "Applied recommended build setting. No immediate benchmark improvement measured, but this aligns with Apple's recommended configuration and positions the project for future Xcode improvements."

有些构建设置是Apple推荐的现代默认值。无论即时基准测试是否显示可衡量的改进，这些设置都应被应用并保留。它们不是投机性优化——它们使项目与Apple工具链的发展方向保持一致，并在未来的Xcode版本中持续体现价值。修复工具绝不能基于单次基准测试结果建议回滚这些设置。

一旦应用就应始终保留的最佳实践设置：

```
COMPILATION_CACHING = YES
```
—— Apple正在积极投入开发此功能；缓存会随每个Xcode版本改进，并在真实工作流中持续发挥作用
```
EAGER_LINKING = YES
```
（Debug模式）—— 允许链接器与编译过程重叠
```
SWIFT_USE_INTEGRATED_DRIVER = YES
```
—— 消除进程间调度开销
```
DEBUG_INFORMATION_FORMAT = dwarf
```
（Debug模式）—— 避免不必要的dSYM生成
```
SWIFT_COMPILATION_MODE = singlefile
```
（Debug模式）—— 增量重编译
```
ONLY_ACTIVE_ARCH = YES
```
（Debug模式）—— 本地构建无需编译所有架构

报告这些设置时，请使用类似措辞："已应用推荐的构建设置。未测得即时基准测试改进，但此设置与Apple的推荐配置保持一致，为项目适配未来Xcode改进做好准备。"

When to recommend revert (speculative changes only)

何时建议回滚（仅针对投机性变更）

For changes that are not best-practice settings (e.g., source refactors, linkage experiments, script phase modifications, dependency restructuring):

If the cumulative pass shows wall-clock regression across all measured build types (standard clean, cached clean, and incremental are all slower), recommend reverting all speculative changes unless the developer explicitly asks to keep specific items for non-performance reasons.
For each individual speculative change: if it shows no median improvement and no cached/incremental benefit either, flag it with
```
Recommend revert
```
and the measured delta.
Distinguish between "outlier reduction only" (improved worst-case but not median) and "median improvement" (improved typical developer wait).
When a change trades off one build type for another (e.g., slower standard clean but faster cached clean), present both numbers clearly and let the developer decide. Frame it as: "Standard clean builds are X.Xs slower, but cached clean builds (the realistic daily workflow) are Y.Ys faster."

对于非最佳实践设置的变更（例如，源码重构、链接实验、脚本阶段修改、依赖重构）：

如果累积测试显示所有被测构建类型（标准干净、缓存干净和增量构建）的耗时均退化，建议回滚所有投机性变更，除非开发者明确要求保留某些非性能原因的项。
对于每个单独的投机性变更：如果未显示中位数改进，也没有缓存/增量构建方面的收益，请标记为"建议回滚"并附上测得的差异。
区分"仅减少异常值"（改善最坏情况但不影响中位数）和"中位数改进"（改善典型开发者等待时间）。
当变更在不同构建类型间进行权衡时（例如，标准干净构建变慢但缓存干净构建变快），请清晰呈现两组数据，由开发者决定。表述方式如下："标准干净构建耗时增加X.X秒，但缓存干净构建（真实日常工作流）耗时减少Y.Y秒。"

Reporting

报告

Lead with the wall-clock result in plain language:

"Your clean build now takes X.Xs (was Y.Ys) -- Z.Zs faster." "Your incremental build now takes X.Xs (was Y.Ys) -- Z.Zs faster."

Then include:

Post-change clean build wall-clock median
Post-change incremental build wall-clock median
Absolute and percentage wall-clock deltas for both
Confidence notes if benchmark noise is high
List of files modified per fix
Any deviations from the original recommendation

If cumulative task metrics improved but wall-clock did not, say plainly: "Compiler workload decreased but build wait time did not improve. This is expected when Xcode runs these tasks in parallel with other equally long work."

If a fix produced no measurable wall-time improvement, note

No measurable wall-time improvement

and suggest whether to keep (e.g. for code quality) or revert.

For changes valuable for non-benchmark reasons (deterministic package resolution, branch-switch caching), label them: "No wait-time improvement expected from this change. The benefit is [deterministic builds / faster branch switching / reduced CI cost]."

Note:

COMPILATION_CACHING

has been measured at 5-14% faster clean builds across tested projects (87 to 1,991 Swift files). The benefit compounds in real developer workflows where the cache persists between builds -- branch switching, pulling changes, and CI with persistent DerivedData. The benchmark script auto-detects this setting and runs a cached clean phase for validation.

首先用直白语言呈现耗时结果：

"你的干净构建现在耗时X.X秒（之前为Y.Y秒）—— 加快了Z.Z秒。" "你的增量构建现在耗时X.X秒（之前为Y.Y秒）—— 加快了Z.Z秒。"

然后包含以下内容：

变更后的干净构建耗时中位数
变更后的增量构建耗时中位数
两者的绝对耗时差异和百分比差异
如果基准测试噪声较大，添加置信度说明
每个修复对应的修改文件列表
与原始建议的任何偏差

如果累积任务指标有所改善但耗时未减少，请直白说明："编译器工作量已减少，但构建等待时间未改善。当Xcode将这些任务与其他耗时相同的任务并行运行时，这种情况是正常的。"

如果修复未带来可衡量的耗时改进，请注明"未测得耗时改进"，并建议是否保留（例如，为了代码质量）或回滚。

对于非基准测试相关的有价值变更（确定性包解析、分支切换缓存），请标注："此变更预计不会减少等待时间。其收益为[确定性构建/更快分支切换/降低CI成本]。"

注意：

COMPILATION_CACHING

在测试项目（87至1991个Swift文件）中测得干净构建速度提升5-14%。在缓存跨构建持续存在的真实开发者工作流中（分支切换、拉取变更、使用持久DerivedData的CI），其收益会持续累积。基准测试脚本会自动检测此设置，并运行缓存干净阶段进行验证。

Execution Report

执行报告

After the optimization pass is complete, produce a structured execution report. This gives the developer a clear summary of what was attempted, what worked, and what the final state is.

Structure:

markdown

undefined

优化完成后，生成结构化的执行报告。这能让开发者清晰了解尝试的内容、有效的措施以及最终状态。

结构：

markdown

undefined

Execution Report

执行报告

Baseline

基准值

Clean build median: X.Xs
Cached clean build median: X.Xs (if applicable)
Incremental build median: X.Xs

干净构建中位数：X.X秒
缓存干净构建中位数：X.X秒（如适用）
增量构建中位数：X.X秒

Changes Applied

已应用变更

#	Change	Actionability	Measured Result	Status
1	Description	repo-local	Clean: X.Xs→Y.Ys, Incr: X.Xs→Y.Ys	Kept / Reverted / Blocked
2	...	...	...	...

序号	变更内容	可操作性	测得结果	状态
1	描述	仓库本地	干净构建：X.X秒→Y.Y秒，增量构建：X.X秒→Y.Y秒	保留 / 回滚 / 阻塞
2	...	...	...	...

Final Cumulative Result

最终累积结果

Clean build median: X.Xs (was Y.Ys) -- Z.Zs faster/slower
Cached clean build median: X.Xs (was Y.Ys) -- Z.Zs faster/slower
Incremental build median: X.Xs (was Y.Ys) -- Z.Zs faster/slower
Net result: Faster / Slower / Unchanged

干净构建中位数：X.X秒（之前为Y.Y秒）—— 加快/变慢Z.Z秒
缓存干净构建中位数：X.X秒（之前为Y.Y秒）—— 加快/变慢Z.Z秒
增量构建中位数：X.X秒（之前为Y.Y秒）—— 加快/变慢Z.Z秒
净结果： 加快 / 变慢 / 无变化

Blocked or Non-Actionable Findings

阻塞或不可操作的发现

Finding: reason it could not be addressed from the repo


Status values:

- `Kept` -- Change improved or maintained build times and was kept.
- `Kept (best practice)` -- Change is a recommended build setting; kept regardless of immediate benchmark result.
- `Reverted` -- Change regressed build times and was reverted.
- `Blocked` -- Change could not be applied due to project structure, Xcode behavior, or external constraints.
- `No improvement` -- Change compiled but showed no measurable wall-time benefit. Include whether it was kept (for non-performance reasons) or reverted.

发现：无法从仓库处理的原因


状态值说明：

- `保留` —— 变更改善或维持了构建时间，已保留。
- `保留（最佳实践）` —— 变更为推荐的构建设置；无论即时基准测试结果如何，均保留。
- `回滚` —— 变更导致构建时间退化，已回滚。
- `阻塞` —— 由于项目结构、Xcode行为或外部约束，无法应用变更。
- `无改进` —— 变更可编译但未带来可衡量的耗时收益。需注明是因非性能原因保留还是已回滚。

Escalation

升级处理

If during implementation you discover issues outside this skill's scope:

Project-level analysis gaps: hand off to
```
xcode-project-analyzer
```
Compilation hotspot analysis: hand off to
```
xcode-compilation-analyzer
```
Package graph issues: hand off to
```
spm-build-analysis
```

如果在实施过程中发现超出此技能范围的问题：

项目级分析缺口：移交至
```
xcode-project-analyzer
```
编译热点分析：移交至
```
xcode-compilation-analyzer
```
包图问题：移交至
```
spm-build-analysis
```

Additional Resources

额外资源

For concrete before/after fix patterns, see references/fix-patterns.md
For build settings best practices, see references/build-settings-best-practices.md
For the recommendation format, see references/recommendation-format.md

具体的修复前后模式，请参见 references/fix-patterns.md
构建设置最佳实践，请参见 references/build-settings-best-practices.md
建议格式，请参见 references/recommendation-format.md