新项目初始化时应先配置最小可用golangci-lint：禁用高噪声linter（如golint、goconst、lll等），启用基础检查（govet、errcheck、staticcheck等），并排除vendor、testdata等目录，确保lint精准有效。
新项目初始化时，直接用默认配置跑 golangci-lint run 很可能报一堆无关紧要甚至误报的问题，这不是工具不好，而是没做最小必要配置——先关掉高噪声、开好基础检查、排除生成/测试代码，三步就能让 lint 真正有用。
为什么新项目一跑就满屏报错
golangci-lint 默认启用约 30+ linter，其中像 goconst（检测重复字面量）、lll（行长度）、dupl（代码重复）在空项目或刚建的 main.go 里极易误触发；而 golint 已被官方弃用，但旧版本仍默认开启，会干扰判断。
- 常见现象：
golangci-lint run输出大量exported function XXX should have comment或line is longer than 120 characters，但你连函数都没写几个 - 根本原因：未禁用冗余 linter，也未跳过
testdata、vendor、mocks等目录 - 关键动作：别急着调参数，先做减法——只保留真正能防 bug 的核心检查器
.golangci.yml 最小可用配置模板
在项目根目录新建 .golangci.yml，内容控制在 20 行内，聚焦「不漏错误、不吵人」：
run:
timeout: 2m
skip-dirs:
- vendor
- testdata
- mocks
- internal/cmd
<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>goconst</li><li>lll</li><li>dupl</li><li>gocyclo # 圈复杂度对新项目意义不大，后期再开</li></ul><p>linters-settings:
errcheck:
check-blank: false # 允许 _ = xxx()，避免初期过度约束
govet:
enable-all: true
disable:</p><ul><li>fieldalignment # 对齐警告在开发早期价值低-
skip-dirs必加：否则testdata里的示例代码会触发unused报错 -
disable比enable-only更安全：明确关掉已知干扰项，而非靠记忆记全要开哪些 -
errcheck.check-blank: false是新手友好设置，避免每行os.Open都得套if err != nil
本地验证与 CI 同步的关键细节
配置写完不等于生效——IDE、CLI、CI 三端行为可能不一致，尤其路径和缓存：
立即学习“go语言免费学习笔记（深入）”；
- 执行
golangci-lint run -v确认读取的是当前目录的.golangci.yml（输出里有Configured options段） - VS Code / GoLand 要重启或手动触发 “Reload Configuration”，否则仍用旧缓存
- CI 中（如 GitHub Actions）务必显式指定配置：
golangci-lint run -c .golangci.yml，不能依赖自动查找 - 首次运行后，
golangci-lint cache status查看缓存位置，若想彻底重来可golangci-lint cache clean
容易被忽略的“活配置”习惯
配置不是写完就扔的静态文件——它得随项目演进动态调整：
- 当团队开始写单元测试，把
tests: true加到run块下，否则testify相关代码不会被govet检查 - 引入第三方 SDK 后，如果其生成代码（如 protobuf）频繁报
unused，直接加skip-files: ["\.pb\.go$"] - 发现某个 linter 总是误报（比如
staticcheck对泛型推导不准），不要全局关，改用//nolint:staticcheck行级抑制 - Go 版本升级后（如从 1.21 → 1.22），检查
go字段是否更新：run: go: "1.22"，否则部分 linter 可能静默降级
最麻烦的从来不是配第一版，而是忘了某次 go mod tidy 后新增的依赖悄悄触发了某个被忽略的 linter 规则——建议把 golangci-lint run 加进 make verify，每次提交前自动过一遍。
