mcpField
S
spm-build-analysis

spm-build-analysis

github.com/avdlee开发1.3k3.4k 次安装28 周前更新
代码仓库

关于 spm-build-analysis

spm-build-analysis 是用于分析 Swift Package Manager 配置是否拖慢 Xcode 构建的技能。它要求先收集证据，并在未经批准时不改写清单或依赖。

主要功能

  1. 01检查包依赖图和构建日志
  2. 02核实本地包是否已链接
  3. 03分析插件与二进制目标
  4. 04评估重构建及 CI 影响
  5. 05验证分支依赖的固定版本

适用场景

  1. 01排查缓慢的 Xcode 全量构建
  2. 02追踪范围过大的增量重构建
  3. 03评估插件对 CI 的影响

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/avdlee/xcode-build-optimization-agent-skill --skill spm-build-analysis

安装后在 Claude Code 中输入/spm-build-analysis确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
build-optimization-sources.md
recommendation-format.md
spm-analysis-checks.md
scripts/
check_spm_pins.py

详细介绍

SPM 构建分析

当包结构、插件或依赖项配置可能导致 Xcode 构建缓慢时，使用此技能。

核心规则

  • 将包分析视为首先收集证据，而不是必须替换依赖项的指令。
  • 区分包图问题与项目设置问题。
  • 未经明确批准，不要重写包清单或依赖项来源。

检查内容

  • Package.swift 和 Package.resolved
  • 本地包与远程包
  • 包插件和构建工具的使用情况
  • 二进制目标的规模
  • 依赖分层、重复导入和潜在循环
  • 显示包相关工作内容的构建日志或计时摘要

给出建议前的验证

在建议中提及任何本地包之前，请确认它确实属于项目的依赖图。Vendor/ 目录中可能包含未关联到任何目标的包。

  • 检查 project.pbxproj 中引用该包路径的 XCLocalSwiftPackageReference 条目。
  • 检查 XCSwiftPackageProductDependency 条目，确认该包的产品至少关联到一个目标。
  • 如果本地包存在于磁盘上，但项目未引用它，请勿将其纳入构建时间相关建议。

建议为跟踪分支的依赖项固定版本时：

  • 使用辅助脚本一次性扫描所有固定到分支的依赖项： 
    python3 scripts/check_spm_pins.py --project App.xcodeproj
    此脚本会对每个固定到分支的包运行 git ls-remote --tags，并报告哪些包有可用于固定版本的标签。
  • 如果没有标签，则建议固定到特定的提交修订哈希，以确保确定性。
  • 注明哪些包固定到分支是因为上游根本没有标签，哪些包虽有标签但仍有意跟踪分支。

重点关注领域

  • 包图结构，以及更改会触发多少下游工作
  • 本地开发和 CI 期间的插件开销
  • 干净环境中体现出的检出或获取成本信号
  • 导致模块重复构建的配置漂移
  • 使用不同宏或选项的包目标共享依赖项所带来的风险
  • 依赖方向违规（功能模块相互依赖，而非依赖共享的底层模块）
  • 模块之间的循环依赖（将共享契约提取到协议模块中）
  • 过大的模块（200 个以上文件）扩大了增量重建范围
  • 使用 @_exported import 的伞形模块造成隐藏的依赖链
  • 缺少接口与实现的分离，阻碍构建并行化
  • 测试目标依赖应用目标，而不是被测模块
  • Swift 宏重建级联：大量使用 Swift 宏（例如 TCA、基于 swift-syntax 的库）可能导致微小的源代码更改触发几乎全量重建，因为宏展开会使下游模块失效
  • 没有预构建二进制文件时，swift-syntax 会针对所有架构进行构建，显著增加干净构建的开销
  • 多平台构建倍增效应：添加辅助平台目标（例如 watchOS）可能导致共享的 SPM 包多次构建（例如 iOS arm64、iOS x86_64、watchOS arm64），使 SwiftCompile、SwiftEmitModule 和 ScanDependencies 任务成倍增加

模块化 SDK 迁移注意事项

将依赖从单体目标迁移到模块化多目标 SDK（例如，将一个总括库替换为独立的 Core、RUM、Logs、Trace 模块）并不会自动缩短构建时间。模块化目标会增加 SwiftCompile、SwiftEmitModule 和 ScanDependencies 任务的数量，因为每个目标都必须单独编译、扫描并生成模块。构建时间方面的权衡取决于项目的并行处理余量，以及实际需要多少个模块化目标。

考虑迁移到模块化 SDK 时：

  • 对比迁移前后的 SwiftCompile 任务总数。
  • 在建议为提升构建速度而迁移之前，对两种配置都进行基准测试。
  • 如果迁移的目的是缩减 API 范围（只导入实际使用的内容），请注意，构建时间可能不变，也可能增加，但导入规范性会有所改善。
  • 只有当项目目前会编译单体 SDK 中大量未使用的部分，且模块化方案能够完全跳过这些未使用部分时，才建议为提升构建速度而迁移到模块化 SDK。

显式模块依赖方面

当同一模块在计时输出中多次出现时，请调查不同的软件包或目标选项是否导致生成了额外的模块变体。统一选项往往比减少少量源代码更重要。

报告格式

对于每项发现，请包含：

  • 证据
  • 受影响的软件包或插件
  • 对干净构建与增量构建可能造成的影响
  • 相关的 CI 影响
  • 预估影响
  • 是否需要审批

如果主要问题与软件包无关，请转交给 xcode-project-analyzer 或 xcode-compilation-analyzer：读取目标技能的 SKILL.md，并在相同的项目上下文中应用其工作流。

其他资源

评论

支持 Markdown