在 Swift 项目中配置并强制执行 SwiftLint…

需要在 Swift 项目里搭建、配置、抑制或接入 CI 的 SwiftLint 代码风格检查时使用。

适用场景

解决思路

1. 默认采用构建工具插件方式：在 Package.swift 中添加 SimplyDanny/SwiftLintPlugins 依赖，并在 target 的 plugins 中加入 .plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")；Xcode 项目则在项目设置中添加该包依赖，并在 target 的 Build Phases 或插件信任对话框中启用；首次构建时在 Xcode 提示中选择 "Trust & Enable All"。
2. 在项目根目录创建 .swiftlint.yml，配置 disabled_rules、opt_in_rules、included、excluded、line_length、type_body_length、file_length 等键；SwiftLint 从调用或插件工作目录加载主配置，并可为每个文件合并最近的嵌套 .swiftlint.yml；传 --config 会覆盖自动发现并禁用嵌套配置查找。
3. 按三类规则选择：默认规则自动启用；opt_in_rules 选择性启用；analyzer_rules 需编译器日志（通过 swiftlint analyze 运行）。新项目先跑 swiftlint rules 查看已启用规则，禁用与团队约定冲突的规则，再逐条添加 opt-in 规则并审查违规；除非有特殊理由，不要用 only_rules。
4. 对已有代码库：先用默认规则集，创建 baseline 抑制所有现存违规，运行与 CI 相同的严格且带 baseline 的命令并修复每个新违规，直到通过后再启用下一条规则或开始下一批清理，逐步消除 baseline 违规且不允许 baseline 增长。
5. 用内联注释抑制特定行：// swiftlint:disable:next force_cast、// swiftlint:disable:this force_try、// swiftlint:disable:previous large_tuple；区域抑制用 // swiftlint:disable <rule> ... // swiftlint:enable <rule>；尽量少用 // swiftlint:disable all。策略上优先针对单条规则而非 all，区域结束后必须重新 enable，生成代码优先用 .swiftlint.yml 的 excluded 路径而非内联抑制，测试目标用子配置而非整体排除。
6. 创建 baseline：运行 swiftlint --write-baseline .swiftlint.baseline 记录当前所有违规；之后用 swiftlint --baseline .swiftlint.baseline 只报告新违规；CI 中传 --baseline 使只有新违规导致构建失败，并随时间修复遗留违规后重新生成。
7. 自动修复：运行 swiftlint --fix（旧别名 --autocorrect）；绝不要在编译前构建阶段运行 --fix，应手动或在专门的 CI 步骤中运行并审查 diff；并非所有规则支持自动修复，可用 swiftlint rules 的 "Correctable" 列查看；运行前先提交或 stash。
8. CI 集成：在 CI 中安装 SwiftLint 并运行 swiftlint --strict --reporter sarif > swiftlint.sarif；常用标志包括 --strict（警告也返回非零）、--reporter sarif（GitHub Advanced Security 兼容）、--reporter json（机器可读）、--reporter checkstyle（Jenkins/SonarQube 兼容）、--baseline .swiftlint.baseline（仅新违规失败）；上传 SARIF 时在 lint 步骤后加 github/codeql-action/upload-sarif。
9. 任何配置、baseline 或规则变更后，在本地或验证任务中运行与 CI 完全相同的 lint 命令；非零退出时检查并修复新违规，再重跑同一命令直到通过，不要仅为隐藏失败而重新生成 baseline。
10. 按项目形态选择集成方式：有 Package.swift 的 SwiftPM 包或 Xcode 项目用 SwiftLintPlugins 构建工具插件；需要 CLI 标志（--fix、--baseline）的 SwiftPM 项目用命令插件 swift package plugin swiftlint；无 SwiftPM 且团队用 Homebrew 的 Xcode 项目用 run script 构建阶段；CI/CD 用 Homebrew 或 Docker 安装后直接运行 swiftlint；pre-commit 钩子用 Homebrew 安装加 .pre-commit-config.yaml 或 git 钩子脚本。
11. 使用分层配置：在子目录放置 .swiftlint.yml 继承并覆盖父配置，例如在 Tests/ 放置放宽的配置禁用 force_unwrapping、force_try 并提高 file_length；也可用 parent_config 配合 HTTPS URL 拉取共享团队配置（支持缓存）；CLI 可传多个 --config，后者覆盖前者的重叠键。
12. 避免常见错误：不要在构建阶段运行 --fix；不要在不理解含义时使用 only_rules；不要用 // swiftlint:disable all 后忘记重新 enable；固定 SwiftLint 版本（SPM 插件解析、Brewfile 或 CI 配置）；不要过度排除（如整体排除 Tests/，应改用放宽的子配置）；注意工具链匹配（SwiftLint 必须与编译项目的 Swift 工具链兼容，否则解析错误）；大型代码库不要一次启用过多 opt-in 规则；配置 included 路径以免递归扫描到 vendored 或生成代码。
13. 按审查清单核对：项目根目录存在 .swiftlint.yml 且显式配置 included/excluded；SwiftLint 版本已固定；每个应检查的 target 启用了构建工具插件；CI 运行 swiftlint --strict（或带 --baseline 增量采用）；baseline 不意外增长且下一条规则或清理批次前 CI 为绿；构建阶段无 --fix/--autocorrect；内联抑制针对具体规则而非 all 并附原因注释；测试目标有合适配置（子配置放宽而非整体排除）；autocorrect 变更在单独提交中审查；新 opt-in 规则逐条添加并达成团队共识。

适用边界 · 注意事项

• 项目不使用 Swift 或不需要 Swift 代码风格检查时。
• 团队尚未确定 Swift 代码风格约定、无法就规则集达成共识时。
• 仅需一次性查看规则列表或文档，而不需要实际配置与强制执行时。