SwiftLint

一款强制实施 Swift 风格和约定的工具，大致基于现已归档的 https://github.com/github/swift-style-guide%E3%80%82SwiftLint 强制实施 Swift 社区普遍接受的风格指南规则。这些规则在诸如 https://github.com/kodecocodes/swift-style-guide 等流行风格指南中有详细描述。

SwiftLint 规则主要基于 https://github.com/swiftlang/swift-syntax%E3%80%82%E9%83%A8%E5%88%86%E8%A7%84%E5%88%99%E4%BB%8D%E9%9C%80%E6%8E%A5%E5%85%A5 Clang 和 SourceKit 以获取类型信息。

本项目遵循 贡献者公约行为准则。参与本项目即表示您同意遵守此准则。

切换语言： https://github.com/realm/SwiftLint/blob/main/README_CN.md%E3%80%81 https://github.com/realm/SwiftLint/blob/main/README_KR.md

视频介绍

如需快速了解 SwiftLint 的概览，建议观看由 JP Simard 于 2017 年 1 月 9 日录制的演示（提供文字稿）：

安装

https://github.com/apple/swift-package-manager

SwiftLint 可用作 命令插件 或 构建工具插件。

将

.package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: " ")

添加到您的 Package.swift 文件中，以自动使用 SwiftLint 的最新版本，或固定依赖到特定版本：

.package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", exact: " ")

其中，将 替换为所需的最低版本或精确版本。

[!NOTE] 直接从 SwiftLint 仓库使用插件存在若干缺点。为避免这些问题并减少开销，强烈建议从专用的 https://github.com/SimplyDanny/SwiftLintPlugins 使用插件，尽管 SwiftLint 仓库中的插件也完全可用。如果倾向于使用 SwiftLint 提供的插件，只需在上述包声明中使用 URL https://github.com/realm/SwiftLint。

然而，https://github.com/SimplyDanny/SwiftLintPlugins 极大地简化了插件的采用过程。它列出了一些导致 SwiftLint 自身提供的插件使用起来非常麻烦的原因。由于插件代码和版本保持同步，两者在功能上没有差异，但使用专用插件仓库可以为您节省大量时间和避免麻烦。

本文档假设您依赖 SwiftLintPlugins。

Xcode 包依赖

使用以下链接将 SwiftLint 添加为 Xcode 项目的包依赖：

Homebrew

brew install swiftlint

CocoaPods

将以下内容添加到您的 Podfile 中：

pod 'SwiftLint'

这将在您下次执行 pod install 时将 SwiftLint 二进制文件和依赖项下载到 Pods/ 目录中，并允许您在脚本构建阶段通过 ${PODS_ROOT}/SwiftLint/swiftlint 调用它。

通过 Cocoapods 安装还可以固定 SwiftLint 的特定版本，而不仅仅是最新版本（Homebrew 就是这种情况）。

请注意，这会将 SwiftLint 二进制文件、其依赖项的二进制文件以及 Swift 二进制库分发版添加到 Pods/ 目录中，因此不建议将此目录提交到 Git 等源代码管理系统。

https://github.com/yonaskolb/mint

mint install realm/SwiftLint

Bazel

将以下内容放入您的 MODULE.bazel 中：

bazel_dep(name = "swiftlint", version = "0.52.4", repo_name = "SwiftLint")

或者将以下内容放入您的 WORKSPACE 中：

WORKSPACE

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
name = "build_bazel_rules_apple",
sha256 = "390841dd5f8a85fc25776684f4793d56e21b098dfd7243cd145b9831e6ef8be6",
url = "https://github.com/bazelbuild/rules_apple/releases/download/2.4.1/rules_apple.2.4.1.tar.gz",
)

load(
"@build_bazel_rules_apple//apple:repositories.bzl",
"apple_rules_dependencies",
)

apple_rules_dependencies()

load(
"@build_bazel_rules_swift//swift:repositories.bzl",
"swift_rules_dependencies",
)

swift_rules_dependencies()

load(
"@build_bazel_rules_swift//swift:extras.bzl",
"swift_rules_extra_dependencies",
)

swift_rules_extra_dependencies()

http_archive(
name = "SwiftLint",
sha256 = "c6ea58b9c72082cdc1ada4a2d48273ecc355896ed72204cedcc586b6ccb8aca6",
url = "https://github.com/realm/SwiftLint/releases/download/0.52.4/bazel.tar.gz",
)

load("@SwiftLint//bazel:repos.bzl", "swiftlint_repos")

swiftlint_repos()

load("@SwiftLint//bazel:deps.bzl", "swiftlint_deps")

swiftlint_deps()

然后您可以使用以下命令在当前目录中运行 SwiftLint：

bazel run -c opt @SwiftLint//:swiftlint

预构建包

从 https://github.com/realm/SwiftLint/releases/latest 下载 SwiftLint.pkg 并运行。

从源代码构建

确保已安装构建工具 Bazel 和最新的 Swift 工具链，并且所有工具都可在您的 PATH 中找到。

要构建 SwiftLint，请克隆此仓库并运行 make install。

设置

[!IMPORTANT] 虽然在编译 Swift 源文件之前运行 SwiftLint 以在出现 lint 违规时提前退出构建似乎很直观，但重要的是要了解 SwiftLint 旨在分析可编译的有效源代码。无法编译的代码很容易导致意外和混乱的结果，尤其是在使用 --fix/--autocorrect 命令行参数执行时。

构建工具插件

SwiftLint 可用作 Swift 包项目 和 Xcode 项目 的构建工具插件。

构建工具插件通过在包/项目目录中定位最顶层的配置文件来确定 SwiftLint 工作目录。如果未在其中找到配置文件，则将包/项目目录用作工作目录。

当插件无法解析 SwiftLint 工作目录时，会抛出错误。例如，在目标的 Swift 文件不在项目目录中的 Xcode 项目中会发生这种情况。

为最大限度地提高与插件的兼容性，请避免需要使用 --config 选项的项目结构。

Swift 包项目

[!NOTE] 需通过 Swift 包管理器 安装。

构建工具插件在构建每个目标时运行。当项目有多个目标时，必须将插件单独添加到所需的目标中。

为此，将插件添加到要进行 lint 的目标中，如下所示：

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

Swift 包命令插件

[!NOTE] 需要通过 Swift Package Manager 安装。

命令插件允许通过命令行运行 SwiftLint，如下所示：

swift package plugin swiftlint

Xcode 项目

[!NOTE] 需要通过 Xcode 包依赖项 安装。

构建工具插件作为每个目标的构建阶段运行。当项目有多个目标时，必须将插件分别添加到所需的目标中。

为此，将 SwiftLintBuildToolPlugin 添加到要进行 lint 的目标的 Build Phases 中的 Run Build Tool Plug-ins 阶段。

[!TIP] 首次使用插件时，出现提示时请务必信任并启用它。如果存在宏构建警告，请选择该警告以信任并启用宏。

对于无人值守使用（例如在 CI 上），可以通过以下任一方式禁用包插件和宏验证：

• 使用 xcodebuild 选项：

-skipPackagePluginValidation
-skipMacroValidation

• 设置 Xcode 默认值：

defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES
defaults write com.apple.dt.Xcode IDESkipMacroFingerprintValidation -bool YES

[!IMPORTANT] 无人值守使用选项会绕过 Xcode 的验证对话框，并隐式信任所有插件和宏，这具有安全隐患。

非预期的 Xcode 项目结构

构建工具插件不直接支持 SwiftLint 配置文件位于包/项目目录之外的项目结构。这是因为无法向构建工具插件传递参数（例如传递配置文件路径）。

如果您的项目结构无法直接与构建工具插件配合使用，请考虑以下任一选项：

• 要使用位于包/项目目录之外的配置文件，可以在该目录中添加一个配置文件，指定指向另一个配置文件的父配置路径，例如 parent_config: path/to/.swiftlint.yml。
• 您也可以考虑使用 运行脚本构建阶段 来替代构建工具插件。

Xcode 运行脚本构建阶段

[!NOTE] 根据所使用的安装方法，运行脚本构建阶段中的 shell 命令语法可能不同，或者可能需要额外配置。有关更多信息，请参阅 安装 说明。

如果构建工具插件不适用于您的项目设置，或者需要额外的自定义设置，可以将 SwiftLint 添加为运行脚本构建阶段。当项目设置依赖于 --config SwiftLint 选项时，或者要在单次 swiftlint 调用中一起 lint 所有目标时，这非常有用。文件包含和排除可以在 .swiftlint.yml 配置 中进行配置。

为此，在主应用目标的 Build Phases 中的 Run Script 阶段（位于 Compile Sources 阶段之后）添加自定义脚本。使用以下脚本实现：

if command -v swiftlint >/dev/null 2>&1
then
swiftlint
else
echo "warning: `swiftlint` command not found - See https://github.com/realm/SwiftLint#installation for installation instructions."
fi

如果您在 Swift 包中使用 SwiftLintPlugin，可以通过以下方式引用 swiftlint 可执行文件：

SWIFT_PACKAGE_DIR="${SWIFT_PACKAGE_DIR:-${BUILD_DIR%Build/*}SourcePackages}"
SWIFTLINT_CMD="$SWIFT_PACKAGE_DIR/artifacts/swiftlintplugins/SwiftLintBinary/SwiftLintBinary.artifactbundle/macos/swiftlint"

if test -f "$SWIFTLINT_CMD" 2>&1
then
"$SWIFTLINT_CMD"
else
echo "warning: `swiftlint` command not found - See https://github.com/realm/SwiftLint#xcode-run-script-build-phase for installation instructions."
fi

[!NOTE] SWIFTLINT_CMD 路径使用默认的 Xcode 配置，并已在 Xcode 15/16 上测试。如果是其他配置（例如自定义 Swift 包路径），请相应调整值。如果使用 -clonedSourcePackagesDirPath 运行 xcodebuild，请在运行脚本前将 SWIFT_PACKAGE_DIR 设置为空。

[!TIP] 取消勾选 Based on dependency analysis（基于依赖分析），以便在所有增量构建上运行 swiftlint，从而抑制未指定输出警告。

Xcode 15.0 注意事项

Xcode 15 做出了一项重大更改，将 ENABLE_USER_SCRIPT_SANDBOXING 构建设置的默认值从 NO 改为 YES。因此，SwiftLint 会遇到与文件权限缺失相关的错误，通常表现为 error: Sandbox: swiftlint(19427) deny(1) file-read-data.

要解决此问题，需要为配置 SwiftLint 的特定目标手动将 ENABLE_USER_SCRIPT_SANDBOXING 设置为 NO。

Apple Silicon 注意事项

如果您在 Apple Silicon 上通过 Homebrew 安装了 SwiftLint，可能会遇到以下警告：

warning: SwiftLint not installed, download from https://github.com/realm/SwiftLint

这是因为 Apple Silicon 上的 Homebrew 默认将二进制文件安装到 /opt/homebrew/bin 文件夹中。要告知 Xcode 在哪里找到 SwiftLint，您可以在构建阶段将 /opt/homebrew/bin 添加到 PATH 环境变量中：

if [[ "$(uname -m)" == arm64 ]]
then
export PATH="/opt/homebrew/bin:$PATH"
fi

if command -v swiftlint >/dev/null 2>&1
then
swiftlint
else
echo "warning: `swiftlint` command not found - See https://github.com/realm/SwiftLint#installation for installation instructions."
fi

或者您可以在 /usr/local/bin 中创建指向实际二进制文件的符号链接：

ln -s /opt/homebrew/bin/swiftlint /usr/local/bin/swiftlint

其他注意事项

如果您还希望修复违规问题，脚本可以运行 swiftlint --fix && swiftlint，而不仅仅是 swiftlint。这意味着所有可修复的违规问题都将被修复，同时确保项目中显示剩余违规问题的警告。

如果您通过 CocoaPods 安装了 SwiftLint，脚本应如下所示：

"${PODS_ROOT}/SwiftLint/swiftlint"

Visual Studio Code

要将 SwiftLint 与 Visual Studio Code 集成，请从市场安装 vscode-swiftlint 扩展。

Fastlane

您可以使用官方的 swiftlint fastlane 操作 在 fastlane 流程中运行 SwiftLint。

多 Swift 版本兼容

SwiftLint 与 SourceKit 集成，因此即使 Swift 不断演进，它也能持续工作！

这也使 SwiftLint 保持轻量，因为它不需要附带完整的 Swift 编译器，只需与您机器上已安装的官方编译器通信即可。

您应始终使用与编译代码相同的工具链运行 SwiftLint。

如果您安装了多个工具链或 Xcode，可能需要覆盖 SwiftLint 的默认 Swift 工具链。

以下是 SwiftLint 确定使用哪个 Swift 工具链的顺序：

• $XCODE_DEFAULT_TOOLCHAIN_OVERRIDE
• $TOOLCHAIN_DIR 或 $TOOLCHAINS
• xcrun -find swift
• /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
• /Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
• ~/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain
• ~/Applications/Xcode-beta.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain

sourcekitd.framework 应位于上述路径值的 usr/lib/ 子目录中。

您还可以将 TOOLCHAINS 环境变量设置为标识 Swift 工具链版本的反向 DNS 表示法：

TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 swiftlint --fix

在 Linux 上，SourceKit 应位于 /usr/lib/libsourcekitdInProc.so 或由 LINUX_SOURCEKIT_LIB_PATH 环境变量指定。

配置

通过在运行 SwiftLint 的目录中添加 .swiftlint.yml 文件来配置 SwiftLint。可配置以下参数：

规则包含：

• disabled_rules：从默认启用的规则集中禁用规则。
• opt_in_rules：启用不属于默认集的规则。特殊标识符 all 会启用所有可选的检查规则，但 disabled_rules 中列出的规则除外。
• only_rules：仅启用此列表中指定的规则。不能与 disabled_rules 或 opt_in_rules 同时指定。
• analyzer_rules：这是一个完全独立的规则列表，仅由 analyze 命令运行。所有分析器规则均为可选启用，因此这是唯一可配置的规则列表，没有 disabled_rules 和 only_rules 的等效项。特殊标识符 all 也可用于此处，以启用所有分析器规则，但 disabled_rules 中列出的规则除外。

# 默认情况下，SwiftLint 使用一组合理的默认规则，您可以根据需要调整。通过运行 `swiftlint rules` 或访问 https://realm.github.io/SwiftLint/rule-directory.html 查看所有可用规则。

# 可以禁用默认启用的规则。
disabled_rules:
- colon
- comma
- control_statement

# 可以启用默认禁用的规则。
opt_in_rules:
- empty_count

# 或者，通过取消注释此选项并删除上述两个选项来显式指定所有规则。
# only_rules:
# - empty_parameters
# - vertical_whitespace

# 仅由 `swiftlint analyze` 运行的规则。这些均为可选启用。
analyzer_rules:
- explicit_self

#  lint 期间要包含的区分大小写的路径。命令行提供的目录路径将被忽略。支持通配符。
included:
- Sources

#  lint 期间要忽略的区分大小写的路径。优先级高于 `included`。支持通配符。
excluded:
- Carthage
- Pods
- Sources/ExcludedFolder
- Sources/ExcludedFile.swift
- Sources/*/ExcludedFile.swift

# 如果为 true，SwiftLint 在未找到可 lint 文件时不会失败。
allow_zero_lintable_files: false

# 如果为 true，SwiftLint 会将所有警告视为错误。
strict: false

# 如果为 true，SwiftLint 会将所有错误视为警告。
lenient: false

# 基准文件的路径，将用于过滤检测到的违规。
baseline: Baseline.json

# 将检测到的违规保存为新基准的路径。
write_baseline: Baseline.json

# 如果为 true，SwiftLint 会在 lint 或分析后检查更新。
check_for_updates: true

# 可配置规则可以自定义。所有规则都支持设置其严重级别。
force_cast: warning # 隐式设置
force_try:
  severity: warning # 显式设置

# 同时具有警告和错误级别的规则可以隐式设置警告级别。
line_length: 110

# 要隐式设置两个级别，请使用数组。
type_body_length:
- 300 # 警告
- 400 # 错误

# 要显式设置两个级别，请使用字典。
file_length:
  warning: 500
  error: 1200

# 命名规则可以为 `min_length` 和 `max_length` 设置警告/错误。此外，它们还可以设置排除的名称和允许的符号。
type_name:
  min_length: 4 # 警告
  max_length: # 警告和错误
    warning: 40
    error: 50
  excluded: i(Phone|Pad|Pod) # 正则表达式模式
  allowed_symbols: ["_"]
identifier_name:
  min_length:
    error: 4 # 仅错误
  excluded: # 通过字符串数组排除
  - id
  - URL
  - GlobalAPIKey

# 默认报告器（SwiftLint 的输出格式）可配置为 `checkstyle`、`codeclimate`、`csv`、`emoji`、`github-actions-logging`、`gitlab`、`html`、`json`、`junit`、`markdown`、`relative-path`、`sarif`、`sonarqube`、`summary` 或 `xcode`（默认）。
reporter: "xcode"

您还可以在配置文件中使用环境变量，方法是在字符串中使用 ${SOME_VARIABLE}。

使用多个配置文件

SwiftLint 提供了多种包含多个配置文件的方式。多个配置文件会合并为一个单一配置，其应用方式与单个配置文件相同。

使用多个配置文件在很多场景下都很有帮助：

例如，可以使用团队范围共享的 SwiftLint 配置，同时允许每个项目通过子配置文件进行覆盖。

团队范围配置：

disabled_rules:
- force_cast

项目特定配置：

opt_in_rules:
- force_cast

子/父配置（本地）

你可以在配置文件中指定 child_config 和/或 parent_config 引用。这些引用应为相对于指定它们的配置文件所在文件夹的本地路径。这甚至可以递归工作，只要没有循环和歧义。

子配置被视为细化，因此具有更高的优先级，而父配置在发生冲突时被视为基础，优先级较低。

以下是一个示例，假设你有以下文件结构：

ProjectRoot
|_ .swiftlint.yml
|_ .swiftlint_refinement.yml
|_ Base
|_ .swiftlint_base.yml

要同时包含细化文件和基础文件，你的 .swiftlint.yml 应如下所示：

child_config: .swiftlint_refinement.yml
parent_config: Base/.swiftlint_base.yml

合并父配置和子配置时，会仔细处理 included 和 excluded 配置，以考虑包含配置文件的目录位置差异。

路径合并遵循以下规则：

1. 每个配置中的 included/excluded 条目相对于该配置文件的目录进行解析。
2. 子条目不覆盖冲突的父条目。
3. 合并后的路径列表计算方式如下：

merged.included = (parent.included - child.excluded) + child.included
merged.excluded = (parent.excluded - child.included) + child.excluded

这意味着子配置可以重新包含被父配置排除的路径，也可以排除被父配置包含的路径。

子/父配置（远程）

与提供本地 child_config/parent_config 引用类似，你可以不引用本地路径，而是直接使用指向配置文件的 URL。为了让 SwiftLint 检测到这些远程引用，它们必须以 http:// 或 https:// 开头。

被引用的远程配置文件甚至可以递归引用其他远程配置文件，但不允许包含本地引用。

使用远程引用时，你的 .swiftlint.yml 可能如下所示：

parent_config: https://myteamserver.com/our-base-swiftlint-config.yml

每次运行 SwiftLint 且有互联网连接时，SwiftLint 会尝试获取每个被引用的远程配置的新版本。如果请求超时，将使用缓存版本（如果可用）。如果没有可用的缓存版本，SwiftLint 将失败——但无需担心，一旦 SwiftLint 成功运行至少一次，就会有缓存版本。

如果需要，可以通过配置文件使用 remote_timeout/remote_timeout_if_cached 指定符手动指定远程配置获取的超时时间。这些值分别默认为 2 秒和 1 秒。

命令行

通过命令行运行 SwiftLint 时，你不仅可以提供一个配置文件，还可以传递一个层次结构，其中第一个配置被视为父配置，最后一个被视为优先级最高的子配置。

仅包含两个配置文件的简单示例如下：

swiftlint --config .swiftlint.yml --config .swiftlint_child.yml

嵌套配置

除主配置（根文件夹中的 .swiftlint.yml 文件）外，您还可以在目录结构中放置其他名为 .swiftlint.yml 的配置文件。对于指定文件，SwiftLint 会从该文件所在目录向上遍历至根配置，并将找到的第一个嵌套 .swiftlint.yml 用作子配置。

该嵌套配置仅适用于其目录子树中的文件。其他子树中的文件继续使用主配置（或其最近的嵌套配置）。

由于 SwiftLint 在向上遍历目录树时会在找到第一个匹配项时停止，每个文件最多合并一个嵌套配置（主配置除外）。

.swiftlint.yml 文件仅在尚未用于构建主配置（例如通过类似以下方式引用：

child_config: Folder/.swiftlint.yml

）的情况下才会被视为嵌套配置。此外，嵌套配置的 parent_config/child_config 规范会被忽略，因为这没有意义。

如果通过 --config 参数显式指定了一个（或多个）SwiftLint 文件，则该配置将被视为覆盖配置，无论目录中是否存在其他 .swiftlint.yml 文件。因此，如果要使用嵌套配置，则不能使用 --config 参数。

许可

https://github.com/realm/SwiftLint/blob/main/LICENSE

关于

SwiftLint 完全由志愿者维护，他们完全利用业余时间为其成功贡献力量。因此，SwiftLint 绝不是商业产品。

请善待将 SwiftLint 作为爱好进行维护的人们，并理解他们的时间有限。通过为项目做贡献、报告问题以及帮助社区中的其他人来支持他们。

特别感谢 MacStadium 提供实体 Mac mini 机器来运行我们的性能测试。

我们也感谢 Realm（现 MongoDB）对项目的初始贡献和设置。