| name | go-linting |
| description | Use when setting up linting for a Go project, configuring golangci-lint, or adding Go checks to a CI/CD pipeline. Also use when starting a new Go project and deciding which linters to enable, even if the user only asks about "code quality" or "static analysis" without mentioning specific linter names. Does not cover code review process (see go-code-review). |
| license | Apache-2.0 |
| metadata | {"sources":"Uber Style Guide"} |
| allowed-tools | Bash(bash:*) |
Go Lint
核心原则
比任何"推荐"的 linter 集合更重要的是：在整个代码库中一致地进行 lint。
一致的 lint 有助于捕获常见问题，并在不过度限制的情况下建立高标准的代码质量。
设置步骤
- 使用下面的配置创建
.golangci.yml
- 运行
golangci-lint run ./...
- 如果出现错误，按类别逐一修复（先格式化，再 vet，再风格）
- 重新运行直到通过
最低推荐 Linter
这些 linter 能捕获最常见的问题，同时保持高质量标准：
注意：revive 是现已弃用的 golint 的现代、更快的替代品。
Lint 运行器：golangci-lint
使用 golangci-lint 作为你的 lint 运行器。参见 uber-go/guide 的 示例 .golangci.yml。
示例配置
在创建新的 .golangci.yml 或将现有配置与推荐基线进行比较时，参见 assets/golangci.yml。
在项目根目录创建 .golangci.yml：
linters:
enable:
- errcheck
- goimports
- revive
- govet
- staticcheck
linters-settings:
goimports:
local-prefixes: github.com/your-org/your-repo
revive:
rules:
- name: blank-imports
- name: context-as-argument
- name: error-return
- name: error-strings
- name: exported
run:
timeout: 5m
运行
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run
golangci-lint run ./pkg/...
额外推荐的 Linter
除了最低集合之外，在生产项目中可以考虑以下 linter：
Nolint 指令
在抑制 lint 发现时，始终说明原因：
_ = logger.Sync()
规则：
- 使用
//nolint:lintername——永远不要使用裸 //nolint
- 将注释放在与发现相同的行
- 在
// 之后包含理由说明
CI/CD 集成
GitHub Actions
name: Lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: stable
- uses: golangci/golangci-lint-action@v6
with:
version: latest
Pre-commit Hook
#!/bin/sh
golangci-lint run --new-from-rev=HEAD~1
使用 --new-from-rev 只对更改的代码进行 lint，保持快速反馈循环。
可用脚本
scripts/setup-lint.sh——生成 .golangci.yml 并运行初始 lint
bash scripts/setup-lint.sh github.com/your-org/your-repo
bash scripts/setup-lint.sh --force github.com/your-org/your-repo
bash scripts/setup-lint.sh --dry-run
bash scripts/setup-lint.sh --json
验证：在生成 .golangci.yml 后，运行 golangci-lint run ./... 验证配置有效并产生预期输出。如果因配置错误而失败，修复后重试。
scripts/setup-lint.sh 生成最低配置（5 个核心 linter）。
对于已有项目，使用 assets/golangci.yml 作为起点——
它增加了 gosec、ineffassign、misspell、gocyclo 和 bodyclose。
快速参考
| 任务 | 命令/操作 |
|---|
| 安装 golangci-lint | go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest |
| 运行 linter | golangci-lint run |
| 对路径运行 | golangci-lint run ./pkg/... |
| 配置文件 | 项目根目录的 .golangci.yml |
| CI 集成 | 在管道中运行 golangci-lint run |
| Nolint 指令 | //nolint:name // 原因——永远不要使用裸 //nolint |
| CI 集成 | 使用 golangci/golangci-lint-action 用于 GitHub Actions |
| Pre-commit | golangci-lint run --new-from-rev=HEAD~1 |
Linter 选择指南
| 当你需要... | 使用 |
|---|
| 错误处理覆盖率 | errcheck |
| 导入格式化 | goimports |
| 风格一致性 | revive |
| Bug 检测 | govet、staticcheck |
| 以上全部 | golangci-lint 配合配置 |
相关技能
