golangci-lint Linters 全览：用help linters与linters命令掌握内置检查器的启用与分类
【免费下载链接】golangci-lintFast linters runner for Go项目地址: https://gitcode.com/gh_mirrors/go/golangci-lint
golangci-lint 是面向 Go 的快速 linter 运行器（Fast linters runner for Go），它聚合了上百个社区与官方静态检查器。本文以官方文档 Linters 概览页 为核心骨架，系统讲解如何通过golangci-lint help linters与golangci-lint linters两条命令查看全部内置 linter、默认启用集合以及当前配置生效的集合，并结合 pkg/commands/help_linters.go、pkg/commands/linters.go 与 pkg/lint/lintersdb/manager.go 等源码，讲清底层分组、默认值与配置解析原理。读完本文，你将能快速审计任意项目当前启用了哪些检查器、哪些默认关闭，并据此精准调整自己的 linter 组合。
文档定位：Linters 入口页在站点中的角色
在官方文档站点中，docs/content/docs/linters/_index.md 是 “Linters” 章节的索引页（front matter 中weight: 3、excludeSearch: true，并带有aliases: /usage/linters/历史别名）。它本身不罗列全部检查器的细节，而是承担三个职责：
- 给出两条最核心的 CLI 命令，快速获取 linter 清单；
- 通过卡片导航指向 Quick Start、CLI、全局配置、Linter 设置等关联文档；
- 通过站点短代码（shortcode）渲染“全部 Linter”列表，并提供 Default / New / Autofix / Fast / Slow / Deprecated 过滤徽章。
也就是说，这篇索引页是“查看与理解 linter 集合”的操作总入口。下文围绕它展开的每一条命令与机制，都能在仓库源码中找到对应实现。
快速上手：两条命令看全所有 linter
命令一：golangci-lint help linters—— 查看支持列表与默认启用状态
文档给出的第一条命令用于查看“支持哪些 linter，以及哪些默认启用/禁用”：
golangci-lint help linters该命令由 pkg/commands/help.go 中的helpCommand注册（lintersCmd.Use = "linters"，Short为 “Display help for linters.”），实际执行逻辑在 pkg/commands/help_linters.go。
关键实现细节（help_linters.go#L50-L68）：
lintersPreRunE中直接以config.NewDefault()构造 linters 数据库管理器lintersdb.NewManager(...)，注释明确说明“该命令不依赖真实配置”（The command doesn't depend on the real configuration），因此它展示的是全量支持清单 + 默认分组，与用户自己的.golangci.yml无关；- 输出时按
lc.FromGroup(config.GroupStandard)判断：属于standard组的 linter 归入“Enabled by default linters”（绿色标题），其余归入“Disabled by default linters”（红色标题），见 help_linters.go#L90-L113； - 每个 linter 条目由
printLinters渲染为名称: 描述 [能力]形式，能力标记包括蓝色fast（非慢速）与绿色auto-fix（支持自动修复），已废弃的 linter 会追加红色[deprecated]标记，且排序时被统一放到列表末尾，见 help_linters.go#L115-L155。
该命令还支持--json输出，便于脚本化消费（help_linters.go#L72-L88），JSON 中每个 linter 包含name、description、groups、fast、autoFix、deprecated、since、originalURL等字段。例如想拿到所有“快速”linter 的名字，可配合 jq 处理：
golangci-lint help linters --json | jq '[ .[] | select(.fast==true) ] | map(.name)'这条 jq 用法并非杜撰：它在 docs/data/configuration_file.json 中
linters.default字段的官方注释里被原样引用，用于说明fast分组的确切构成。
命令二：golangci-lint linters—— 查看当前配置实际启用的集合
文档给出的第二条命令用于查看“你的配置启用了哪些 linter”：
golangci-lint linters与help linters不同，linters命令会加载真实配置。其实现位于 pkg/commands/linters.go：
preRunE（linters.go#L71-L88）通过config.NewLintersLoader(...)加载配置文件与命令行 flag（含--config相关 flag），随后以加载后的配置构造lintersdb.NewManager(...)；execute（linters.go#L90-L136）调用dbManager.GetEnabledLintersMap()得到最终启用的 linter 集合，再与全量支持列表比对，划分为“Enabled by your configuration linters”与“Disabled by your configuration linters”两组输出；- 同样支持
--json（fs.BoolVar(&c.opts.JSON, "json", ...)），此时输出结构为{"Enabled": [...], "Disabled": [...]}。
因此，help linters回答的是“这个版本支持什么”，而linters回答的是“我这个项目现在跑哪些”。前者适合了解工具能力边界，后者适合排障、审计 CI 配置、确认某条规则是否真的在生效。
默认 linter 分组与linters.default配置语义
两条命令输出的背后，是 pkg/config/linters.go 定义的四组预置分组常量：
const ( GroupStandard = "standard" GroupAll = "all" GroupNone = "none" GroupFast = "fast" )对应配置文件linters.default字段的可选值（见 docs/data/configuration_file.json 中linters段的官方注释与示例）：
standard（默认值）：启用文档所称的 “Default” linter 集合，即所有被打上standard组标记的检查器；all：默认启用全部 linter；none：默认不启用任何 linter（此时仅保留不可禁用的typecheck）；fast：只启用被标记为 “fast”（非慢速）的检查器。
分组解析逻辑位于 pkg/lint/lintersdb/manager.go#L131-L205 的build()方法：
- 第 136 行
groupName := cmp.Or(m.cfg.Linters.Default, config.GroupStandard)表明：未显式配置linters.default时，默认值即standard； GroupStandard分支仅筛选lc.FromGroup(config.GroupStandard)的 linter（manager.go#L157-L167），这也是help linters中 “Enabled by default” 一组的直接判定依据；GroupFast分支通过lc.IsSlowLinter()排除慢速 linter（manager.go#L145-L155）；- 随后按顺序应用
linters.enable追加、linters.disable剔除（支持别名，见注释 “it's important to use lc.Name() nor name because name can be alias”，manager.go#L173-L185）； - 若启用了
linters.fast-only（仅 flag 选项，见 pkg/config/linters.go#L19），再统一移除慢速 linter； - 最后强制补入
typecheck——它不是真正的 linter 且不可禁用（manager.go#L196-L202），所以你在任何配置下都会看到它。
一个典型配置片段（对照 docs/data/configuration_file.json 的示例字段）：
linters: # 默认集：standard / all / none / fast # Default: standard default: standard # 在默认集基础上额外启用 enable: - revive - gocritic - staticcheck # 从结果中剔除 disable: - errcheck注意一个容易踩的坑：linters.enable/linters.disable中不能出现格式化器（formatter，如gofmt、gofumpt、gci、goimports、golines、swaggo）。pkg/config/linters.go#L41-L49 的validateNoFormatters会在配置校验阶段直接报错 “%s is a formatter”。格式化器需要放到独立的formatters:配置段中管理。
“所有 Linter”列表与站点过滤徽章
文档索引页的 “All Linters” 部分通过 Hugo 短代码渲染完整列表：
{{< golangci/items/filter >}} {{< golangci/items/filter-badge data="default" content="Default" >}} {{< golangci/items/filter-badge data="new" content="New" >}} {{< golangci/items/filter-badge data="autofix" content="Autofix" >}} {{< golangci/items/filter-badge data="fast" content="Fast" >}} {{< golangci/items/filter-badge data="slow" content="Slow" >}} {{< golangci/items/filter-badge data="deprecated" content="Deprecated" >}} {{< /golangci/items/filter >}} {{< cards >}} {{< golangci/items/cards path="linters" data="linters_info" >}} {{< /cards >}}列表数据源是 docs/data/linters_info.json（共 1100+ 行），每个条目包含name、desc、originalURL、internal、isSlow、since、canAutoFix、groups等字段。例如前几条：
arangolint：面向 arangodb client 的约定检查器，isSlow: true，自 v2.2.0 起支持；asciicheck：检查代码标识符是否含非 ASCII 字符，isSlow: false（快），自 v1.26.0 起支持；canonicalheader：检查net/http.Header是否使用规范头部，带canAutoFix: true，自 v1.58.0 起支持。
这些字段与help linters --json输出的fast、autoFix、deprecated、since等标记一一对应，也与linters_info.json中isSlow、canAutoFix直接映射——站点徽章过滤与 CLI 能力标记本质上是同一份数据的两套呈现。
各徽章语义可对照 CLI 输出理解：
| 站点徽章 | 含义 | 对应数据/代码依据 |
|---|---|---|
| Default | 属于standard分组，默认启用 | groups含standard；manager.go 的GroupStandard分支 |
| New | 较新版本加入 | since字段（如 v2.x 系列） |
| Autofix | 支持自动修复 | canAutoFix字段；help_linters.go 的auto-fix标记 |
| Fast | 非慢速检查器 | isSlow: false；!lc.IsSlowLinter()判定 |
| Slow | 需要完整程序加载/较慢 | isSlow: true；lc.IsSlowLinter() |
| Deprecated | 已废弃（仍可用但有告警） | IsDeprecated()判定 |
从数据到运行：linter 的注册与执行优化
理解列表之后，值得看一眼这些 linter 是如何被“组织起来”的。仓库中 pkg/lint/lintersdb/ 目录是 linter 的“数据库”实现：
builder_linter.go：内置 linter 的构建器，其中多个 linter 通过WithGroups(config.GroupStandard)挂入 standard 分组（如 builder_linter.go#L232、#L434、#L461 等）；builder_plugin_go.go与builder_plugin_module.go：支持通过 Go 插件（plugin 模块）扩展第三方 linter，扩展的 linter 也可加入 standard 组（builder_plugin_go.go#L72）；manager.go：Manager是“所有 linter（内置或插件）的数据库”，提供GetAllSupportedLinterConfigs()、GetEnabledLintersMap()等访问方法（manager.go#L25-L34）。
从源码结构还可以看到运行期的一项关键优化：GetOptimizedLinters()（manager.go#L96-L128）会把多个可增量加载的 go/analysis linter 合并进一个 metalinter（combineGoAnalysisLinters，manager.go#L207-L261），通过共享一次加载的数据来提升速度——这也是项目“Fast linters runner”定位在实现层面的体现。需要注意的是，整程序加载模式（goanalysis.LoadModeWholeProgram）的 linter 不参与合并，因为“同时运行 whole-program 与增量分析器在 CPU 与内存上都不划算”（manager.go#L218-L221）。
常见排查场景与操作建议
把上面两条命令组合起来，可以覆盖几类高频需求：
- 审计项目当前启用的检查器：运行
golangci-lint linters，检查 “Enabled by your configuration linters” 是否与预期一致，确认误启/漏启； - 判断某个新 linter 是否可用：运行
golangci-lint help linters | grep <name>，确认名称、能力标记（fast/auto-fix）与[deprecated]状态； - 在 CI 中做断言：用
golangci-lint linters --json解析Enabled/Disabled数组，与团队规范比对； - 按性能取舍：用
golangci-lint help linters --json筛选fast==true的子集，或直接在配置中设置linters.default: fast/ 追加--fastflag，在开发迭代期快速反馈。
无论选择哪条命令，最终配置入口都在linters:配置段（pkg/config/linters.go 定义了default、enable、disable、fast-only、settings、exclusions等字段），完整的示例字段与注释可查阅 docs/data/configuration_file.json 中的linters条目，或站点中与之关联的 Linter 设置文档。
总结
golangci-lint help linters与golangci-lint linters是掌握 golangci-lint 检查器生态的两个抓手：前者基于默认配置输出全量支持清单与默认启用状态，后者加载你的真实配置输出实际生效集合。二者背后是standard/all/none/fast四组默认分组（pkg/config/linters.go）与 pkg/lint/lintersdb/manager.go 中build()的解析顺序——先取默认组，再应用enable/disable，最后强制保留typecheck。借助--json输出，你可以把 linter 集合的审计工作完全脚本化，持续守护项目的代码质量基线。
【免费下载链接】golangci-lintFast linters runner for Go项目地址: https://gitcode.com/gh_mirrors/go/golangci-lint
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
