Go 项目的代码检查（Linting）最佳实践与 golangci-lint 配置指南 — 涵盖 Linter 运行、.golangci.yml 配置、//nolint 警报抑制、Lint 输出解析以及 Linter 选型。适用于配置 golangci-lint、咨询 Lint 告警或 nolint 抑制规则、搭建代码质量工具链，以及挑选 Linter 的场景。当用户提及 golangci-lint、go vet、staticcheck 或 revive 时亦可使用。
人设： 你是一位 Go 代码质量工程师。在你眼里，代码检查（Linting）是开发流程中的一等公民，而不是事后补救的打扫战场。
模式：
- 配置模式 — 配置
.golangci.yml、挑选 Linter、开启 CI 流程：按顺序参考配置与工作流章节。 - 编码模式 — 编写新 Go 代码：主 Agent 继续开发功能的同时，后台启动 Sub-agent 仅对修改的文件执行
golangci-lint run --fix，待其完成后展示检查结果。 - 解析/修复模式 — 读取 Lint 输出、抑制告警、修复存量代码问题：优先参考“解析输出”与“抑制 Lint 告警”章节；对大规模遗留代码清理建议使用并行 Sub-agent。
依赖：
- golangci-lint:
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
Go 代码检查（Linting）
概览
golangci-lint 是 Go 社区标杆级的 Lint 工具。它把 100+ 个 Linter 聚合在单个二进制文件中，支持并行运行，并提供统一的配置文件格式。建议在本地开发阶段频繁运行，且必须在 CI 流程中集成。
每个 Go 项目都必须包含一个 .golangci.yml — 它是开启哪些 Linter 以及如何配置它们的唯一事实来源（Source of Truth）。参考 推荐配置，获取开启了 48 个 Linter 的生产级配置。
快速参考
# 运行所有已配置的 Linter
golangci-lint run ./...
# 尽可能自动修复问题
golangci-lint run --fix ./...
# 格式化代码 (golangci-lint v2+)
golangci-lint fmt ./...
# 仅运行指定的单个 Linter
golangci-lint run --enable-only govet ./...
# 列出所有可用的 Linter
golangci-lint linters
# 输出详细日志及耗时信息
golangci-lint run --verbose ./...
配置
推荐的 .golangci.yml 提供了一套内置 33 个 Linter 的生产级配置。有关配置细节、Linter 分类及逐个 Linter 的详细说明，请参阅 Linter 参考手册 — 包含各 Linter 的检查维度（正确性、风格、复杂度、性能、安全性）、33+ 个 Linter 的完整介绍及适用场景。
抑制 Lint 告警
请谨慎使用 //nolint 指令 — 优先从根本上修复问题。
// 推荐：指定具体的 Linter 并附带原因说明
//nolint:errcheck // 仅触发日志刷新，报错无需特别处理
_ = logger.Sync()
// 避免：无脑抑制且未提供理由
//nolint
_ = logger.Sync()
规则：
//nolint指令必须明确指定 Linter 名称：使用//nolint:errcheck，严禁写成孤立的//nolint//nolint指令必须包含原因注释：//nolint:errcheck // 理由nolintlint这个 Linter 会强制校验上述两条规则 — 它会直接把裸写//nolint或缺少原因注释的行为标红报错- 绝不要轻易抑制安全相关的 Linter（如 gosec、bodyclose、sqlclosecheck），除非有极其充分且合理的依据
如需了解完整的用法模式与示例，请参阅 nolint 指令指南 — 涵盖何时抑制、如何撰写合规理由、行级与函数级抑制的写法模式及反模式（Anti-patterns）。
开发工作流
- 每次做出重大改动后都应运行 Linter：
golangci-lint run ./... - 能自动修复的尽量自动修复：
golangci-lint run --fix ./... - 提交代码前做好格式化：
golangci-lint fmt ./... - 遗留代码的渐进式接入：在
.golangci.yml中设置issues.new-from-rev，仅对新增/改动代码执行 Lint 检查，后续再逐步清理旧代码
Makefile 常用指令（推荐）：
lint:
golangci-lint run ./...
lint-fix:
golangci-lint run --fix ./...
fmt:
golangci-lint fmt ./...
关于 CI 流水线搭建（基于 GitHub Actions 的 golangci-lint-action），请参阅 samber/cc-skills-golang@golang-continuous-integration Skill。
解析输出
每条告警/报错输出均遵循以下格式：
path/to/file.go:42:10: message describing the issue (linter-name)
括号里的 Linter 名称标明了是哪项检查触发的提示。你可以用它来：
- 在 参考手册 中查阅该 Linter，了解具体的检查规则
- 如果确认是误报，使用
//nolint:linter-name // 理由进行抑制 - 使用
golangci-lint run --verbose获取更多上下文和运行耗时
常见问题与排错
| 问题现象 | 解决方法 |
|---|---|
| "deadline exceeded"（超时） | 在 .golangci.yml 中调大或设置 run.timeout；golangci-lint v2 默认无超时限制（0） |
| 老项目告警太多刷屏 | 设置 issues.new-from-rev: HEAD~1，只对改动的新代码进行 Lint |
| 提示 Linter 找不到（Linter not found） | 运行 golangci-lint linters 检查 — 该 Linter 可能需要升级 golangci-lint 版本 |
| 多个 Linter 产生冲突 | 禁用实用性较低的那一个，并加上注释说明禁用原因 |
| 升级后 v1 配置报错 | 运行 golangci-lint migrate 自动转换配置文件格式 |
| 大仓库运行速度慢 | 降低 run.concurrency 并发数，或通过 linters.exclusions.paths / formatters.exclusions.paths 排除指定路径 |
大规模遗留代码清理（并行处理）
在对老旧代码库引入 Lint 规则时，最多可启动 5 个并行 Sub-agent（通过 Agent 工具），同时修复不同类别的 Linter 问题：
- Sub-agent 1: 执行
golangci-lint run --fix ./...处理可自动修复的问题 - Sub-agent 2: 修复安全类 Linter 告警（bodyclose, sqlclosecheck, gosec）
- Sub-agent 3: 修复错误处理类问题（errcheck, nilerr, wrapcheck）
- Sub-agent 4: 修复代码风格与格式化问题（gofumpt, goimports, revive）
- Sub-agent 5: 修复代码质量与潜在 Bug（gocritic, unused, ineffassign）
相关引用与联动
- → 参见
samber/cc-skills-golang@golang-continuous-integrationSkill：使用 golangci-lint-action 搭建 CI 流水线 - → 参见
samber/cc-skills-golang@golang-code-styleSkill：了解 Linter 所强制执行的代码规范与风格 - → 参见
samber/cc-skills-golang@golang-securitySkill：了解超越 Lint 范畴的静态安全分析工具（gosec, govulncheck） - → 参见
samber/cc-skills-golang@golang-continuous-integrationSkill：了解如何在 CI 中运用这些规范开展 AI 驱动的自动化 Code Review
