flint — 快速 lint

CLI 参考 · 检查机制 · Linters · 为什么选择 flint？ · 替代方案

Flint 是一个快速、简单的 lint 运行器，不会拖慢你的 AI 编码。

📖 阅读博客文章：Flint — 一个不会拖慢你的 AI agent 的 linter 配置

快速 — 原生执行（无 Docker），并行，感知 diff （仅处理已更改的文件），可选（未声明的工具不会运行），小二进制文件由 mise 缓存
本地与 CI 对齐 — 一个二进制文件，一个配置模型，本地默认值针对日常工作进行了调整，并在 CI 中提供更广泛的覆盖
合理的默认值 — flint init 快速搭建可用的配置，大多数仓库可以沿用生成的默认值
有主见的配置 — Flint 为每个 linter 选择规范的配置文件名，同时仍允许你将它们保留在诸如 .github/config 的目录中
对 AI 友好 — 默认安静：干净的运行不输出任何内容，--fix 仅显示仍需处理的内容
所有权分离 — 专用的 linters 和 formatters 拥有其文件类型，以避免规则重叠和 editor-config 冲突
可预测且可更新的 linter 版本 — lint 行为保持稳定，直到仓库有意更新固定的 linter 版本，例如通过 Renovate 更新 mise.toml
跨平台 — Linux、macOS、Windows
自动修复 — --fix 修复可修复的问题；报告仍需审查的问题

阅读背景与原则和替代方案/比较。

入门指南

安装

安装 mise.
将 Flint 添加到您的仓库：
```
mise use --pin aqua:grafana/flint
```
可选：如果你使用 Renovate，请在 init 之前创建你的 Renovate 配置。然后 Flint 可以对其进行修补以包含 Flint 预设，这有助于将 linter 和 Flint 更新分组在一起，减少 PR 噪音。

[!IMPORTANT] Flint 的共享 default.json 预设现在仅针对当前设置。它不再附带用于更新 SHA 固定 raw.githubusercontent.com/.../<sha>/... # vX.Y.Z 引用或 mise.toml 中 *_VERSION 变量的旧版自定义管理器。如果你的仓库仍然依赖这些 v1 模式，请在扩展预设之前保留你自己的自定义管理器。
让 Flint 搭建设置：
```
mise exec -- flint init
```

在 flint init 期间，你可以：

选择要启用的 linter
添加标准的 mise lint 任务
在需要时编写 flint.toml
如果仓库中尚不存在，则创建 .github/workflows/lint.yml
将 lint 指南添加到 AGENTS.md 或 CLAUDE.md（或创建 AGENTS.md）

如果你想要非交互式设置，请运行 mise exec -- flint init --yes，然后修剪生成的 linter 固定版本。

关于实际设置示例，请参阅 grafana/docker-otel-lgtm 的 mise.toml， flint.toml，以及 CI workflow。

可选：安装一个 git hook，在每次提交前运行 flint run --fix：
```
mise exec -- flint hook install
```

使用

对于普通的本地使用，请运行：

mise run lint:fix

Flint 旨在保持安静。一次干净的运行不会输出任何内容。--fix 会静默修复它能修复的问题，并打印出仍需处理的事项——包括审查项以及提交任何修复的提醒：

[shellcheck]

In bad.sh line 2:
echo $1
     ^-- SC2086 (info): Double quote to prevent globbing and word splitting.
...
flint: fixed: cargo-fmt — commit before pushing | review: shellcheck

简洁到足以供 AI 代理使用，对人类也很友好。

默认情况下，Flint 仅检查已更改的受跟踪文件。 使用 --full 可检查所有匹配的受跟踪文件。Flint 还会跳过在 .gitattributes 中标记为 linguist-generated 的文件；建议优先使用这种方式而非仅限 Flint 的排除项，以便 GitHub 和其他工具能够复用相同的元数据。

有关更多命令和标志，请参阅 CLI 参考。

[!NOTE] 在极少数情况下（目前仅 renovate-deps），故障可能仅在 CI 中显示。这是一种刻意的性能优化——请参阅自适应运行。当这种情况发生时，flint 会打印用于在本地复现的命令（通常是 --full 或 linter 名称）。

有关 Flint 贡献者工作流程和本地测试技巧，请参阅 CONTRIBUTING.md。

Linters

语言

名称	检查器	格式化器
C#	—	`dotnet-format`
Go	`golangci-lint`	`gofmt`
Java	`checkstyle`	`google-java-format`
JavaScript / TypeScript	`biome`	`biome-format`
Kotlin	`ktlint`	`ktlint`
Python	`ruff`	`ruff-format`
Rust	`cargo-clippy`	`cargo-fmt`

文件 / 格式

名称	检查器	格式化器
Dotenv	`dotenv-linter`	`dotenv-linter`
JSON	`biome`	`biome-format`
Markdown	`rumdl`	`rumdl`
Shell	`shellcheck`	`shfmt`
TOML	—	`taplo`
XML	`xmllint`	—
YAML	`ryl`	`ryl`

工具 / CI

名称	检查
Dockerfile	`hadolint`
GitHub Actions	`actionlint` / `zizmor`
Kubernetes manifests	`kube-linter`

通用

名称	检查	描述
EditorConfig	`editorconfig-checker`	EditorConfig 合规性
Flint 配置	`flint-setup`	Flint 管理的配置和 `mise.toml` 布局
许可证头	`license-header`	必需的文件头文本
链接	`lychee`	损坏的链接
Renovate	`renovate-deps`	依赖项更新配置
拼写	`typos`	源文件和文本文件中的拼写

FAQ

Flint 如何确定要运行哪些 linter？

Flint 会根据你仓库中的 mise.toml 来激活检查：如果其中声明了由 Flint 管理的工具，则该检查处于激活状态；如果未声明，Flint 将跳过它。

排除文件不被 lint 的最佳方式是什么？

Flint 从不 lint 未跟踪的文件。这个问题是关于在 git 中已跟踪的文件。

主要有三个选项：

在 .gitattributes 中使用 linguist-generated 标记生成的文件
通过 settings.exclude 在 flint.toml 中添加仓库范围的 Flint 排除项
当该工具需要 Flint 不应全局管理的行为时，在 linter 自身的配置中使用工具特定的排除项

推荐： 尽可能使用 .gitattributes 来处理生成的文件。这可以让 Flint、GitHub 和其他工具共享相同的生成文件元数据。有关详细信息，请参阅 CLI 参考。

版本控制

本项目使用语义化版本控制。破坏性变更将在 CHANGELOG.md 中记录，并会导致主版本号升级。

发布

请参阅 RELEASING.md。