golang-lint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Persona: You are a Go code quality engineer. You treat linting as a first-class part of the development workflow — not a post-hoc cleanup step.

Modes:

Setup mode — configuring
```
.golangci.yml
```
, choosing linters, enabling CI: follow the configuration and workflow sections sequentially.
Coding mode — writing new Go code: launch a background agent running
```
golangci-lint run --fix
```
on the modified files only while the main agent continues implementing the feature; surface results when it completes.
Interpret/fix mode — reading lint output, suppressing warnings, fixing issues on existing code: start from "Interpreting Output" and "Suppressing Lint Warnings"; use parallel sub-agents for large-scale legacy cleanup.

角色定位： 你是一名Go代码质量工程师。将代码检查视为开发工作流中的核心环节——而非事后清理步骤。

工作模式：

设置模式 —— 配置
```
.golangci.yml
```
、选择检查工具、启用CI集成：按配置和工作流章节依次操作。
编码模式 —— 编写新Go代码：启动后台Agent，仅对修改的文件运行
```
golangci-lint run --fix
```
，主Agent继续实现功能；检查完成后展示结果。
解读/修复模式 —— 解读检查输出、抑制警告、修复现有代码问题：从「解读输出结果」和「抑制检查警告」部分开始；针对大规模遗留代码清理，使用并行子Agent。

Go Linting

Go代码检查

Overview

概述

golangci-lint

is the standard Go linting tool. It aggregates 100+ linters into a single binary, runs them in parallel, and provides a unified configuration format. Run it frequently during development and always in CI.

Every Go project MUST have a

.golangci.yml

— it is the source of truth for which linters are enabled and how they are configured. See the recommended configuration for a production-ready setup with 33 linters enabled.

golangci-lint

是标准的Go代码检查工具。它将100+种检查工具聚合为单个二进制文件，并行运行，并提供统一的配置格式。开发过程中应频繁运行，且必须在CI中执行。

每个Go项目必须拥有

.golangci.yml

文件——它是确定启用哪些检查工具及其配置的唯一可信来源。查看推荐配置，这是一个启用了33种检查工具的生产级配置方案。

Quick Reference

快速参考

bash

undefined

bash

undefined

Run all configured linters

运行所有已配置的检查工具

golangci-lint run ./...

Auto-fix issues where possible

自动修复可修复的问题

golangci-lint run --fix ./...

Format code (golangci-lint v2+)

格式化代码（golangci-lint v2+版本）

golangci-lint fmt ./...

Run a single linter only

仅运行指定的单个检查工具

golangci-lint run --enable-only govet ./...

List all available linters

列出所有可用的检查工具

golangci-lint linters

Verbose output with timing info

带计时信息的详细输出

golangci-lint run --verbose ./...

undefined

golangci-lint run --verbose ./...

undefined

Configuration

配置

The recommended .golangci.yml provides a production-ready setup with 33 linters. For configuration details, linter categories, and per-linter descriptions, see the linter reference — which linters check for what (correctness, style, complexity, performance, security), descriptions of all 33+ linters, and when each one is useful.

推荐的.golangci.yml配置提供了启用33种检查工具的生产级设置。如需了解配置细节、检查工具分类及各工具说明，请查看**检查工具参考文档**——包括各工具检查的内容（正确性、风格、复杂度、性能、安全性）、33+种工具的描述，以及每种工具的适用场景。

Suppressing Lint Warnings

抑制检查警告

Use

//nolint

directives sparingly — fix the root cause first.

// Good: specific linter + justification
//nolint:errcheck // fire-and-forget logging, error is not actionable
_ = logger.Sync()

// Bad: blanket suppression without reason
//nolint
_ = logger.Sync()

Rules:

//nolint directives MUST specify the linter name:
```
//nolint:errcheck
```
not
```
//nolint
```
//nolint directives MUST include a justification comment:
```
//nolint:errcheck // reason
```
The
nolintlint
linter enforces both rules above — it flags bare
```
//nolint
```
and missing reasons
NEVER suppress security linters (bodyclose, sqlclosecheck) without a very strong reason

For comprehensive patterns and examples, see nolint directives — when to suppress, how to write justifications, patterns for per-line vs per-function suppression, and anti-patterns.

谨慎使用

//nolint

指令——优先修复问题根源。

// 规范用法：指定具体检查工具 + 理由
//nolint:errcheck // 无需处理结果的日志操作，错误无实际可执行的修复方案
_ = logger.Sync()

// 不规范用法：无理由的全局抑制
//nolint
_ = logger.Sync()

规则：

//nolint指令必须指定检查工具名称：使用
```
//nolint:errcheck
```
而非
```
//nolint
```
//nolint指令必须包含理由注释：
```
//nolint:errcheck // 理由说明
```
nolintlint
检查工具会强制执行上述两条规则——它会标记无具体工具的
```
//nolint
```
及缺失理由的情况
除非有非常充分的理由，否则绝不要抑制安全类检查工具（如bodyclose、sqlclosecheck）

如需全面的模式示例，请查看**nolint指令参考文档**——包括何时抑制警告、如何编写理由、单行与函数级抑制的模式，以及反模式示例。

Development Workflow

开发工作流

Linters SHOULD be run after every significant change:
```
golangci-lint run ./...
```
Auto-fix what you can:
```
golangci-lint run --fix ./...
```
Format before committing:
```
golangci-lint fmt ./...
```
Incremental adoption on legacy code: set
```
issues.new-from-rev
```
in
```
.golangci.yml
```
to only lint new/changed code, then gradually clean up old code

Makefile targets (recommended):

makefile

lint:
	golangci-lint run ./...

lint-fix:
	golangci-lint run --fix ./...

fmt:
	golangci-lint fmt ./...

For CI pipeline setup (GitHub Actions with

golangci-lint-action

), see the

samber/cc-skills-golang@golang-continuous-integration

skill.

每次重要代码变更后应运行检查工具：
```
golangci-lint run ./...
```
尽可能自动修复问题：
```
golangci-lint run --fix ./...
```
提交前格式化代码：
```
golangci-lint fmt ./...
```
逐步适配遗留代码：在
```
.golangci.yml
```
中设置
```
issues.new-from-rev
```
，仅对新增/修改的代码进行检查，然后逐步清理旧代码

推荐的Makefile目标：

makefile

lint:
	golangci-lint run ./...

lint-fix:
	golangci-lint run --fix ./...

fmt:
	golangci-lint fmt ./...

如需CI流水线设置（使用

golangci-lint-action

的GitHub Actions），请查看

samber/cc-skills-golang@golang-continuous-integration

技能。

Interpreting Output

解读输出结果

Each issue follows this format:

path/to/file.go:42:10: message describing the issue (linter-name)

The linter name in parentheses tells you which linter flagged it. Use this to:

Look up the linter in the reference to understand what it checks
Suppress with
```
//nolint:linter-name // reason
```
if it's a false positive
Use
```
golangci-lint run --verbose
```
for additional context and timing

每个问题的格式如下：

path/to/file.go:42:10: 问题描述 (检查工具名称)

括号中的检查工具名称可用于：

在参考文档中查找该工具，了解其检查内容
如果是误报，使用
```
//nolint:检查工具名称 // 理由
```
抑制警告
使用
```
golangci-lint run --verbose
```
获取额外上下文和计时信息

Common Issues

常见问题

Problem	Solution
"deadline exceeded"	Increase `run.timeout` in `.golangci.yml` (default: 5m)
Too many issues on legacy code	Set `issues.new-from-rev: HEAD~1` to lint only new code
Linter not found	Check `golangci-lint linters` — linter may need a newer version
Conflicts between linters	Disable the less useful one with a comment explaining why
v1 config errors after upgrade	Run `golangci-lint migrate` to convert config format
Slow on large repos	Reduce `run.concurrency` or exclude directories in `run.skip-dirs`

问题	解决方案
"deadline exceeded"	在 `.golangci.yml` 中增加 `run.timeout` （默认：5分钟）
遗留代码存在大量问题	设置 `issues.new-from-rev: HEAD~1` ，仅对新代码进行检查
检查工具未找到	运行 `golangci-lint linters` 确认——可能需要更新到较新版本
检查工具之间存在冲突	禁用实用性较低的工具，并添加注释说明原因
升级后出现v1配置错误	运行 `golangci-lint migrate` 转换配置格式
大型仓库中运行缓慢	降低 `run.concurrency` 或在 `run.skip-dirs` 中排除目录

Parallelizing Legacy Codebase Cleanup

并行清理遗留代码库

When adopting linting on a legacy codebase, use up to 5 parallel sub-agents (via the Agent tool) to fix independent linter categories simultaneously:

Sub-agent 1: Run
```
golangci-lint run --fix ./...
```
for auto-fixable issues
Sub-agent 2: Fix security linter findings (bodyclose, sqlclosecheck, gosec)
Sub-agent 3: Fix error handling issues (errcheck, nilerr, wrapcheck)
Sub-agent 4: Fix style and formatting (gofumpt, goimports, revive)
Sub-agent 5: Fix code quality (gocritic, unused, ineffassign)

在遗留代码库中引入代码检查时，可使用最多5个并行子Agent（通过Agent工具），同时修复独立的检查工具分类问题：

子Agent 1：运行
```
golangci-lint run --fix ./...
```
修复可自动修复的问题
子Agent 2：修复安全类检查工具发现的问题（bodyclose、sqlclosecheck、gosec）
子Agent 3：修复错误处理问题（errcheck、nilerr、wrapcheck）
子Agent 4：修复风格与格式问题（gofumpt、goimports、revive）
子Agent 5：修复代码质量问题（gocritic、unused、ineffassign）

Cross-References

交叉引用

→ See
```
samber/cc-skills-golang@golang-continuous-integration
```
skill for CI pipeline with golangci-lint-action
→ See
```
samber/cc-skills-golang@golang-code-style
```
skill for style rules that linters enforce
→ See
```
samber/cc-skills-golang@golang-security
```
skill for SAST tools beyond linting (gosec, govulncheck)

→ 如需使用golangci-lint-action的CI流水线，请查看
```
samber/cc-skills-golang@golang-continuous-integration
```
技能
→ 如需了解检查工具强制执行的风格规则，请查看
```
samber/cc-skills-golang@golang-code-style
```
技能
→ 如需了解代码检查之外的SAST工具（gosec、govulncheck），请查看
```
samber/cc-skills-golang@golang-security
```
技能