swiftlint

SwiftLint

SwiftLint 通过根据可配置的规则集检查源文件，来强制执行 Swift 风格和约定。本指南涵盖设置、配置、规则选择、抑制、CI 集成和推广策略。

SwiftLint 是一种风格强制工具，而不是风格指南。有关 Swift 命名和设计约定的基础内容，请参阅 swift-api-design-guidelines。有关架构模式，请参阅 swift-architecture。

目录

• 推荐设置
• 配置
• 规则选择策略
• 抑制
• 基线
• 自动修正
• CI 集成
• 集成决策树
• 多配置
• 常见错误
• 审查清单
• 参考资料

---

推荐设置

默认方式：通过 SimplyDanny/SwiftLintPlugins 使用构建工具插件。

将插件包添加到 Package.swift，或通过 Xcode 的包依赖项添加：

// Package.swift
dependencies: [
  .package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: "<reviewed-version>")
]

对于 SwiftPM 目标，应用该插件：

.target(
    name: "MyApp",
    plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")]
)

对于没有 Package.swift 的 Xcode 项目，请在项目设置中添加包依赖项，然后在目标的 Build Phases 中启用插件，或在包的插件信任对话框中启用。

构建工具插件会在每次构建时自动运行 SwiftLint。无需运行脚本。

首次构建：Xcode 会提示你信任该插件。为 SwiftLintPlugins 包选择“Trust & Enable All”。

有关其他方式（运行脚本、命令插件、Homebrew CLI），请参阅 references/plugins-run-scripts-and-integrations.md。

配置

在项目根目录创建 .swiftlint.yml。SwiftLint 会从调用目录或插件工作目录加载主配置；自动发现配置时，还可以为每个文件合并最近的嵌套 .swiftlint.yml。传入 --config 会覆盖自动发现，并停用嵌套配置查找。

# .swiftlint.yml — conservative starter config
disabled_rules:
  - trailing_whitespace
  - todo

opt_in_rules:
  - empty_count
  - closure_spacing
  - force_unwrapping
  - sorted_imports
  - vertical_whitespace_opening_braces
  - private_swiftui_state
  - unhandled_throwing_task
  - accessibility_label_for_image

included:
  - Sources
  - Tests

excluded:
  - .build
  - DerivedData
  - "**/.build"
  - "**/Generated"

line_length:
  warning: 140
  error: 200

type_body_length:
  warning: 300
  error: 500

file_length:
  warning: 500
  error: 1000

主要配置选项：

键	用途
disabled_rules	关闭默认启用的规则
opt_in_rules	启用默认未启用的规则
only_rules	_仅_使用列出的规则（不能与 disabled_rules/opt_in_rules 同时使用）
analyzer_rules	需要编译器日志的规则（通过 swiftlint analyze 运行）
baseline	用于抑制已知违规项的现有基线文件路径
write_baseline	SwiftLint 应写入新基线文件的路径
included	要检查的路径（默认：当前目录）
excluded	要跳过的路径
strict	将所有警告提升为错误
lenient	将所有错误降级为警告
allow_zero_lintable_files	未找到 Swift 文件时抑制错误
reporter	输出格式：xcode（默认）、json、checkstyle、sarif、csv、emoji 等

有关完整配置详情，包括严重级别调整、环境变量插值以及嵌套/远程配置，请参阅 references/adoption-and-configuration.md。

规则选择策略

SwiftLint 提供三类规则：

1. 默认规则 — 自动启用，涵盖广泛认可的约定
2. 可选规则 — 默认禁用，可通过 opt_in_rules 选择性启用
3. 分析器规则 — 需要编译器日志，通过 analyzer_rules 启用

可在 https://realm.github.io/SwiftLint/rule-directory.html 浏览完整的分类列表。

新项目的推荐做法：

1. 从默认规则开始。运行 swiftlint rules 查看已启用的规则。
2. 禁用与团队既定约定冲突的规则。
3. 一次添加一条可选规则。提交每项新增规则前，先检查违规情况。
4. 除非有特定理由要从零开始，否则不要使用 only_rules。

现有代码库的推荐做法：

1. 从默认规则集开始。
2. 创建基线（参见基线），以抑制所有现有违规。
3. 运行 CI 使用的相同严格且支持基线的命令，并修复每一项新违规。
4. 反复运行，直到检查通过，再启用其他规则或开始下一批清理工作。
5. 逐步减少基线中的违规，不要接受基线扩大。

无需抄录或记忆规则目录。需要时，请在官方规则目录中查找规则标识符和配置选项。

抑制

当某条规则产生误报，或违规是有意为之且经过审核时，可针对特定行抑制 SwiftLint。

// swiftlint:disable:next force_cast
let view = object as! UIView

let legacy = try! JSONDecoder().decode(T.self, from: data) // swiftlint:disable:this force_try

// swiftlint:disable:previous large_tuple

禁用某个代码区域：

// swiftlint:disable cyclomatic_complexity
func complexRouter(...) { ... }
// swiftlint:enable cyclomatic_complexity

禁用所有规则（谨慎使用）：

// swiftlint:disable all
// ... generated or legacy code ...
// swiftlint:enable all

规范：

• 优先使用针对单条规则的抑制，而不是 all。
• 区域结束后务必重新启用规则。
• 对于生成的代码，优先在 .swiftlint.yml 中使用 excluded 路径，而不是行内抑制。
• 对于容忍度不同的测试目标，请使用子配置（参见多个配置）。

有关完整的抑制语法，请参见 references/rules-suppressions-and-baselines.md。

基线

基线可让你在现有代码库中采用 SwiftLint，而无需先修复所有遗留违规。

创建基线：

swiftlint --write-baseline .swiftlint.baseline

这会记录当前所有违规。后续运行会与此基线进行比较，只报告新违规。

使用基线：

swiftlint --baseline .swiftlint.baseline

在 CI 中传入 --baseline，这样只有新违规会导致构建失败。随着时间推移，修复遗留违规并重新生成基线，逐步减少基线中的违规。

有关基线工作流和推广策略，请参见 references/rules-suppressions-and-baselines.md。

自动修正

SwiftLint 可以自动修复部分违规：

swiftlint --fix
# or the legacy alias:
swiftlint --autocorrect

警告：

• 绝不要将 --fix 用作编译前的构建阶段。 自动修正会修改源文件。如果每次构建都自动运行，就会形成难以预测的编辑—构建循环，还可能掩盖真正的问题。
• 手动运行 --fix，或在专用的 CI 步骤中运行，然后检查差异。
• 并非所有规则都支持自动修正。查看 swiftlint rules——“Correctable”列会显示哪些规则可以自动修正。
• 运行 --fix 前，务必提交或暂存更改。

CI 集成

CI 是主要的强制执行环节。CI 检查可确保没有人合并会增加违规数量的代码。

推荐的 CI 模式：

# GitHub Actions example
- name: Lint
  run: |
    brew install swiftlint
    swiftlint --strict --reporter sarif > swiftlint.sarif

CI 关键选项：

标志	效果
--strict	出现警告时（不仅是错误时）以非零状态退出
--reporter sarif	输出与 GitHub Advanced Security 兼容
--reporter json	输出机器可读内容
--reporter checkstyle	与 Jenkins/SonarQube 兼容
--baseline .swiftlint.baseline	仅在出现新违规时失败

若要将 SARIF 上传到 GitHub 代码扫描，请在 lint 步骤后添加 github/codeql-action/upload-sarif。

更改任何配置、基线或规则后，请在本地或验证任务中运行与 CI 完全相同的 lint 命令。如果退出状态非零，请检查并修复新增的违规，然后重新运行相同的命令，直到通过；不要仅为掩盖失败而重新生成基线。

有关完整的 CI 配方和报告器详情，请参阅 references/plugins-run-scripts-and-integrations.md。

集成决策树

根据项目形态选择运行 SwiftLint 的方式：

场景	推荐的集成方式
SwiftPM 包或包含 Package.swift 的 Xcode 项目	通过 SwiftLintPlugins 使用构建工具插件
需要 CLI 标志（--fix、--baseline）的 SwiftPM 项目	命令插件：swift package plugin swiftlint
不使用 SwiftPM、团队使用 Homebrew 的 Xcode 项目	运行脚本构建阶段
CI/CD 流水线	通过 Homebrew 或 Docker 安装，直接运行 swiftlint
Pre-commit 钩子	安装 Homebrew + .pre-commit-config.yaml 或 git 钩子脚本

本地开发首选构建工具插件，因为它无需配置 PATH，可通过包解析固定 SwiftLint 版本，并会在构建时自动运行。

有关各集成方式的详细设置说明，请参阅 references/plugins-run-scripts-and-integrations.md。

多个配置

SwiftLint 支持分层配置文件。子目录中的 .swiftlint.yml 会继承父级配置并覆盖其中的设置。

常见模式：

• 宽松的测试配置：在 Tests/ 中放置 .swiftlint.yml，禁用 force_unwrapping 并提高 file_length
• 严格的模块配置：在共享模块目录中放置更严格的 .swiftlint.yml
• 远程配置：使用带 HTTPS URL 的 parent_config 拉取团队共享配置（支持缓存）

# Tests/.swiftlint.yml — child config
disabled_rules:
  - force_unwrapping
  - force_try

file_length:
  warning: 800

也可以在 CLI 中传入多个配置：

swiftlint --config .swiftlint.yml --config .swiftlint-extra.yml

对于重叠的键，后面的配置会覆盖前面的配置。

有关嵌套配置解析、远程配置以及 CLI 多配置的详情，请参阅 references/adoption-and-configuration.md。

常见错误

1. 在构建阶段运行 --fix。 每次构建时自动修复会导致源代码出现不可预测的修改。请手动运行 --fix。

2. 不了解 only_rules 的影响就使用它。 这会禁用除所列规则外的所有规则。大多数团队应改用 disabled_rules + opt_in_rules。

3. 使用 // swiftlint:disable all 禁用规则后忘记重新启用。 这会导致文件剩余部分的所有 lint 检查都被静默禁用。

4. 不固定 SwiftLint 版本。 不同版本的默认规则不同。请使用构建工具插件（通过 SPM 固定版本），或在 Brewfile / CI 配置中固定版本。

5. 排除范围过宽。 完全排除 Tests/ 意味着测试代码不会经过任何 lint 检查。请改用规则较宽松的子配置。

6. 忽略工具链不匹配问题。 SwiftLint 必须使用与项目编译时相同的 Swift 工具链构建，或与之兼容。工具链不匹配会导致解析错误。有关多工具链的指南，请参阅 references/plugins-run-scripts-and-integrations.md。

7. 在大型代码库中一次性启用过多 opt-in 规则。 这会造成大量违规，让人难以应对。请逐步添加规则，并使用基线。

8. 未配置 included 路径。 如果不设置 included，SwiftLint 会递归扫描工作目录，可能会扫描到供应商提供的代码或生成的代码。

审查清单

• 项目根目录中存在 .swiftlint.yml，并明确设置了 included/excluded 路径
• 已固定 SwiftLint 版本（通过 SPM 插件解析、Brewfile 或 CI 配置）
• 为所有需要 lint 检查的目标启用了构建工具插件
• CI 运行 swiftlint --strict（或在逐步采用时使用 --baseline）
• 基线没有意外增长，并且在处理下一批规则或清理工作之前 CI 状态为绿色
• 构建阶段没有使用 --fix / --autocorrect
• 内联抑制针对具体规则，而不是 all
• 内联抑制附有说明原因的注释
• 测试目标有适当的配置（通过子配置放宽规则，而不是完全排除）
• 自动更正产生的更改在单独的提交中审查
• 新增 opt-in 规则时，每次只添加一条，并取得团队共识

参考资料

• references/adoption-and-configuration.md — 安装方式、.swiftlint.yml 深入介绍、严重级别调整、环境变量、嵌套配置 / 远程配置、推出策略
• references/plugins-run-scripts-and-integrations.md — 构建工具插件、命令插件、运行脚本、CI 配方、多工具链指南、VS Code、Fastlane、Docker、pre-commit
• references/rules-suppressions-and-baselines.md — 默认规则、opt-in 规则与分析器规则、抑制语法、基线工作流、误报处理
• references/rule-reference.md — 随附的完整规则索引，供本地查阅；请使用 swiftlint rules 或官方规则目录核实最新详情
• references/custom-rules-and-analyze.md — 正则表达式自定义规则、Swift 自定义规则（简要介绍）、swiftlint analyze、编译器日志工作流
• SwiftLint 文档 — 官方文档
• SwiftLint 规则目录 — 完整的分类规则列表
• SimplyDanny/SwiftLintPlugins — 推荐的插件包