golangci-lint忽略机制分三层:整目录跳过(如vendor、internal/gen)、单文件/函数级忽略(//nolint紧贴行尾)、单行注释绕过;配置须用.golangci.yml、顶格缩进、显式指定路径,生成代码应统一归入skip-dirs目录。

golangci-lint 的忽略机制分三层:整目录跳过、单文件/函数级忽略、单行注释绕过——别混用,否则容易漏检或失效。
怎么用 skip-dirs 安全跳过 vendor 和生成代码
最常用也最容易出错的是目录级跳过。golangci-lint 默认确实跳过 vendor,但这个“默认”极其脆弱:
- 只要你在
.golangci.yml里写了run.skip-dirs: [](空数组),它就覆盖默认值,vendor立刻被扫进去 - 写了
disable-all: true却没补skip-dirs块,也会让默认跳过逻辑完全失效 - 路径必须写成
- vendor,不是- ./vendor(多余)也不是- /vendor(会被当绝对路径失败) - 如果项目用了
third_party或deps这类自定义第三方目录,也得一并加进skip-dirs
推荐写法(放在 .golangci.yml 根层级):
run:
skip-dirs:
- vendor
- testdata
- internal/gen
- docs注意:skip-dirs 是前缀匹配,vendor 能同时跳过 vendor/ 和 myapp/vendor/;但对 replace 指向的本地路径(如 replace example.com/lib => ../lib),它不生效——linter 只看实际文件路径,不解析 go.mod 语义。
立即学习“go语言免费学习笔记(深入)”;
//nolint 注释为什么加了还报错
这是高频误操作:写对了位置才生效,写错等于没写。
- 必须紧贴代码行末尾,中间不能有空格、换行或块注释干扰:✅
log.Println("x") //nolint,❌log.Println("x") // nolint(带空格) - 只作用于所在行,不跨行:想忽略下一行?把
//nolint放在上一行末尾 - 想忽略整个函数?把
//nolint放在func xxx() {那行末尾 - 不能用在
import行上——import未使用需靠_或重构解决,//nolint对它无效 - 只对
golangci-lint run生效;直接跑staticcheck或go vet会无视它
指定 linter 更精准:比如只关 goconst 不动 unused,写成 //nolint:goconst;多个用逗号分隔://nolint:goconst,unused。
配置文件不生效的三个硬性前提
很多“忽略没用”其实是配置根本没加载,不是规则写错了。
- 文件名必须是
.golangci.yml(点开头 + yml 小写),不是.golangci.yaml、golangci.yml或带 BOM 的 UTF-8 文件 - 必须和
go.mod在同一目录;monorepo 中每个 module 都要单独放一份,不继承 - YAML 缩进只能用空格,且
run、linters、linters-settings必须顶格平级——缩进多一格或少一格,整个配置静默失效,退回到仅启用govet和errcheck的默认集
CI 中尤其要显式传参:golangci-lint run --config=.golangci.yml,别依赖自动发现。
真正容易被忽略的是:生成代码(如 pb.go、mock_*.go、docs/doc.go)既不能靠 skip-dirs 漏掉(否则 errcheck 会对 proto.Unmarshal 报错),也不能靠 //nolint 逐行加(维护成本爆炸)。唯一可靠做法是把它们统一放进一个目录(如 internal/gen),然后用 skip-dirs 整体屏蔽。


















