Go Modules 项目必须显式配置 .golangci.yml，否则会回退到启用 golint、typecheck 等已弃用或冗余 linter 的默认配置，导致误报、panic、超时或与 Go 1.21+ 不兼容。
golangci-lint 在 Go Modules 项目中必须显式配置 .golangci.yml，否则默认启用大量 linter（含已弃用项），容易误报、卡死或与 Go 版本不兼容。
为什么 Go Modules 项目不能跳过配置文件
Go Modules 本身不提供 lint 规则，golangci-lint 启动时若找不到 .golangci.yml，会回退到内置的“默认配置”——它在 v1.54+ 中仍启用 golint（已归档）、typecheck（与 go build 冗余）等低效或冲突项。尤其在 go.mod 指定 go 1.21+ 的项目中，这些检查可能因 AST 解析差异直接 panic 或超时。
常见错误现象：golangci-lint run 卡住超过 2 分钟、报 failed to load program: typechecker error、或在 CI 中因 govet 检查失败而中断。
- Modules 项目依赖树更复杂，需靠
run.modules-download-mode: readonly避免 lint 过程意外修改go.sum - 生成代码（如
pb.go、mock_*.go）必须通过skip-dirs或exclude-rules显式排除，否则errcheck会对proto.Unmarshal报错 - 多模块仓库（monorepo）下，
run.cwd和issues.exclude要按子模块路径单独约束，不能只靠根目录配置
最小可用 .golangci.yml 必须包含的三项
以下配置能覆盖 90% Go Modules 项目的实际需求，且与 go 1.21–1.23 兼容：
立即学习“go语言免费学习笔记（深入）”；
run:
timeout: 2m
modules-download-mode: readonly
skip-dirs:
- vendor
- testdata
- internal/gen # 常见生成代码目录
<p>linters:
enable:</p><ul><li>govet</li><li>errcheck</li><li>staticcheck</li><li>unused</li><li>ineffassign
disable:</li><li>golint # 已归档，官方明确不维护</li><li>typecheck # <code>go build</code> 已覆盖，且易与 Modules 冲突</li></ul><p>linters-settings:
staticcheck:
checks: ["all"]
errcheck:
check-type-assertions: true
check-blank: false注意：staticcheck 的 checks: ["all"] 是显式开启全部检查（包括 SA1019 弃用警告），比默认更严格；而 errcheck 关掉 check-blank 可避免对 _ = os.Remove(...) 类写法误报。
CI/CD 中运行时的关键参数
在 GitHub Actions 或 GitLab CI 中，golangci-lint run 必须加参数控制行为，否则会因环境差异失败：
- 始终加
--fast：跳过需要完整类型信息的 linter（如gosimple），避免 Modules 下类型解析失败 - 用
--out-format=github-actions（GitHub）或--out-format=gitlab-ci（GitLab）让错误直接标在 PR 行号上 - 禁止在 CI 中加
--fix：自动修复可能破坏生成代码或格式化风格，应仅限本地 pre-commit 使用 - 缓存
~/.cache/golangci-lint目录，否则每次下载规则集耗时增加 30s+
示例 GitHub Actions 片段：
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.23'
- name: Install golangci-lint
run: |
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $GITHUB_WORKSPACE/bin v1.54.2
- name: Run linters
run: $GITHUB_WORKSPACE/bin/golangci-lint run --fast --out-format=github-actions
env:
GOLANGCI_LINT_CACHE: $HOME/.cache/golangci-lintVS Code 和 GoLand 的 IDE 集成要点
IDE 插件默认读取项目根目录的 .golangci.yml，但两个细节常被忽略：
- GoLand 的
Go | 静态分析器设置里，必须勾选使用配置并指定.golangci.yml路径，否则它会无视文件、只用 IDE 内置规则 - VS Code 的
go.lintTool设置为"golangci-lint"后，还需确认go.toolsEnvVars包含GOPATH，否则golangci-lint找不到go.mod导致 “no Go files” 错误 - 编辑器中波浪线提示延迟高？在
.golangci.yml的run下加concurrency: 2，避免占用全部 CPU 影响编辑体验
最易被忽略的一点：当项目用 replace 指向本地模块（如 replace example.com/lib => ../lib）时，golangci-lint 默认不检查 replace 路径下的代码——必须在 run.skip-dirs 中显式移除该路径，或改用 issues.exclude 白名单机制。
