Ktlint 命令行工具安装与使用指南

Ktlint 是一个强大的 Kotlin 代码风格检查工具，本文将详细介绍如何安装和使用 Ktlint 的命令行接口（CLI）。

安装 Ktlint

手动下载安装

您可以直接下载 Ktlint 的发布版本，下载后需要赋予执行权限：

curl -sSLO https://example.com/path/to/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/

如果您的系统没有安装 curl，可以使用 wget 替代：

wget -qO- https://example.com/path/to/ktlint > ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/

验证下载完整性

为了确保下载的文件未被篡改，您可以验证 PGP 签名：

curl -sS https://example.com/pgp_keys.asc | gpg --import && gpg --verify ktlint.asc

使用包管理器安装

Ktlint 支持多种包管理器安装方式：

macOS 使用 Homebrew：

brew install ktlint

macOS 使用 MacPorts：

port install ktlint

Linux/macOS 使用 SDKMAN!：

sdk install ktlint

基本使用

默认检查

在项目目录下运行以下命令，Ktlint 会递归检查所有 Kotlin 文件（.kt 和 .kts）：

ktlint

自动格式化

Ktlint 可以自动修复大多数风格问题：

ktlint --format
# 或简写
ktlint -F

指定检查范围

您可以使用 glob 模式指定要检查的文件：

# 检查 src 目录下所有 .kt 文件，但排除测试文件
ktlint 'src/**/*.kt' '!src/**/*Test.kt'

高级功能

自定义规则集

Ktlint 支持加载自定义规则集：

ktlint --ruleset=/path/to/custom-ruleset.jar

报告生成

Ktlint 支持多种报告格式：

# 生成分组报告
ktlint --reporter=plain?group_by_file

# 生成汇总报告
ktlint --reporter=plain-summary

# 生成多种格式报告
ktlint --reporter=plain --reporter=checkstyle,output=report.xml

基线文件

对于大型项目，可以创建基线文件忽略已有问题：

ktlint --baseline=ktlint-baseline.xml

编辑器配置

生成 .editorconfig 文件模板：

ktlint generateEditorConfig ktlint_official

Git 集成

Ktlint 可以集成到 Git 工作流中：

# 安装预提交钩子
ktlint installGitPreCommitHook

# 安装预推送钩子
ktlint installGitPrePushHook

其他实用选项

• --color：启用彩色输出
• --help：显示帮助信息
• --version：显示版本信息
• --stdin：从标准输入读取代码检查
• --log-level：设置日志级别（trace, debug, info, warn, error, none）

Windows 用户注意事项

在 Windows 系统上，您可以通过以下方式运行 Ktlint：

1. 使用提供的 ktlint.bat 批处理文件
2. 通过 Git Bash 运行
3. 使用 Java 直接运行：java -jar ktlint

通过本文介绍的方法，您可以轻松地将 Ktlint 集成到您的开发流程中，确保 Kotlin 代码风格的一致性。Ktlint 的强大功能和灵活性使其成为 Kotlin 开发者的必备工具。