golangci-lint Go 代码质量

FreeGuideOnline 最新 2026-07-14

bash curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

安装完成后，确保 `$(go env GOPATH)/bin` 在你的 `PATH` 中。

### 方式二：通过 Go 直接安装
需要 Go 1.21 及以上版本。
```bash
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

方式三：使用包管理器

macOS（Homebrew）：
```
brew install golangci-lint
```
Linux（snap）：
```
sudo snap install golangci-lint
```
Windows（Scoop）：
```
scoop install golangci-lint
```

验证安装：

golangci-lint --version

第一次运行

进入任意 Go 项目目录，直接执行：

golangci-lint run

该命令会使用默认配置对项目进行审查。如果项目中存在已知问题，你会看到类似以下输出：

main.go:5:2: should not use T(context.Background()) in tests (exitAfterDefer)
main.go:8:14: Error return value is not checked (errcheck)

每一行都指出了文件、行号、问题描述以及对应的 linter 名称。

配置方式

默认配置就够了？

golangci-lint 的默认配置包含一组适用大多数项目的 linter，兼顾准确性和运行速度。你可以先用默认配置运行，根据反馈再调整。

创建配置文件 `.golangci.yml`

在项目根目录创建 .golangci.yml，可以细粒度控制启用的 linter、输出设置、运行规则等。一个典型的基础配置：

linters:
  enable:
    - errcheck
    - gosimple
    - govet
    - ineffassign
    - staticcheck
    - unused
linters-settings:
  errcheck:
    check-blank: true
run:
  timeout: 5m
  tests: true

更丰富的示例可从官方配置参考获取。

常用配置项说明

linters.enable：显式开启的 linter 列表。
linters.disable：关闭某些恼人或暂时不适用的 linter。
run.timeout：设置分析总超时，如 10m。
run.skip-dirs：跳过的目录，如 vendor、third_party。
issues.exclude 或 issues.exclude-rules：通过正则或规则屏蔽已知警告。

集成到日常工作流

使用命令行快速检查

golangci-lint run ./...          # 检查整个项目
golangci-lint run ./pkg/...      # 只检查某个子包
golangci-lint run --fix          # 自动修复可修复的问题

在 VS Code 中集成

安装 Go 官方扩展后，在 .vscode/settings.json 中添加：

{
  "go.lintTool": "golangci-lint",
  "go.lintFlags": [
    "--fast"
  ]
}

保存文件时会实时显示 lint 结果。

集成到 CI/CD（GitHub Actions 示例）

在项目根目录创建 .github/workflows/lint.yml：

name: Lint
on: [push, pull_request]
jobs:
  golangci:
    name: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - name: golangci-lint
        uses: golangci/golangci-lint-action@v6
        with:
          version: latest
          args: --timeout=5m

每次提交代码时，便自动执行 lint 检查，避免问题代码流入主分支。

Linter	作用
`errcheck`	检查未处理的错误返回值
`gosimple`	提出更简洁的 Go 代码建议
`govet`	检测 Go 标准库中 vet 能发现的常见错误
`ineffassign`	检测已赋值但从未使用的变量
`staticcheck`	功能强大的静态分析合集，包含大量实用检查
`unused`	检查未使用的常量、变量、函数等
`bodyclose`	检查 HTTP 响应体是否关闭
`noctx`	检查 http.Request 是否遗漏 context
`sqlclosecheck`	检查 `sql.Rows` 和 `sql.Stmt` 是否关闭

启用自动修复

部分 linter 能够自动修复代码问题，可以在提交前运行：

golangci-lint run --fix

请注意，自动修复默认只处理安全、无破坏性的问题（如格式化、未使用变量命名等）。谨慎在 CI 中使用 --fix，通常建议仅在本地使用。

忽略特定问题

有时候必须忽略某些 lint 警告。可以通过注释在代码中临时禁用：

仅忽略下一行：
```
//nolint:errcheck
doSomething()
```
忽略整个文件：在文件开头添加：
```
//nolint
```

在配置中永久排除：

issues:
  exclude-rules:
    - path: _test\.go
      linters:
        - gosec

常见问题排查

1. 运行超时

如果项目庞大，默认超时可能不够。在配置中增加：

run:
  timeout: 10m

2. 内存占用过高

调整并行数：

run:
  concurrency: 4

3. 提示 `go: could not download`

确保 GOPROXY 设置正确，可尝试：

export GOPROXY=https://goproxy.io,direct

4. 与 `vendor` 目录冲突

默认会跳过 vendor 目录，但若未正确跳过，手动添加：

run:
  skip-dirs:
    - vendor

5. 如何查看所有可用 linter

golangci-lint help linters