golangci-lint 在 gRPC 项目中易报错,因默认扫描所有 .go 文件(含自动生成的 .pb.go 和 _grpc.pb.go),触发如 exported func 应有注释等误报;最稳妥方案是在 .golangci.yml 中通过 run.skip-dirs 按路径(如 pb、gen)排除生成目录,或用 issues.exclude-rules 正则匹配 *_grpc.pb.go$ 等文件,避免依赖不稳定的 glob 模式。

golangci-lint 为什么在 gRPC 项目里容易报错
因为生成的 .pb.go 和 _grpc.pb.go 文件默认不加 //nolint,而 golangci-lint 会扫描所有 .go 文件——包括这些自动生成代码。常见误报有:exported func ... should have comment、func name will be used as ... by other packages、ST1016: method returns unexported type 等。这些不是你写的逻辑问题,是 protoc-gen-go 生成结果的固有风格。
如何让 golangci-lint 跳过生成代码
最稳妥的方式是在 .golangci.yml 中配置 run.skip-dirs 或 issues.exclude-rules,而不是靠文件名后缀(因为有些团队把生成代码放在 pkg/pb/ 下,有些放 api/gen/):
- 推荐用路径排除:在
run.skip-dirs加上生成目录,例如pb、gen、proto - 若必须按文件名过滤,可用
issues.exclude-rules匹配.*_grpc\.pb\.go$和.*\.pb\.go$ - 不要写
**/*.pb.go—— glob 模式在某些版本中不生效,优先用正则 - 确保
skip-dirs值是相对于项目根目录的相对路径,且不以/开头(否则会被忽略)
proto 文件变更后 lint 报错但编译正常,怎么回事
这是典型的「lint 与生成逻辑不同步」:你改了 .proto,但没重新运行 protoc,导致 .pb.go 还是旧的;而 golangci-lint 扫描的是旧文件,里面可能引用了已删掉的字段或 service 方法,触发 SA9003: this value is never used 或 U1000: field X is unused 类警告。但 Go 编译器只检查语法和符号存在性,不深挖未使用字段。
- CI 中务必把
protoc生成步骤放在golangci-lint之前 - 本地开发可加 Makefile 规则:先
make gen再make lint - 如果用
buf generate,注意它默认不覆盖已有文件;加--force或清空目标目录再生成
buf + golangci-lint 协同时要注意什么
buf 自带 lint(buf lint),但它检查的是 .proto 语义,比如 GO_PACKAGE_PREFIX 是否一致、package 是否合法;而 golangci-lint 检查的是生成后的 Go 代码。两者不重叠,但容易混淆责任边界:
-
buf lint不报exported func must have comment,那是golangci-lint的事 - 若
buf.gen.yaml里漏了--go-grpc_opt=paths=source_relative,生成的 import 路径错乱,golangci-lint会报import "xxx" not used或cannot find package—— 但这其实是 buf 配置错误,不是 lint 本身的问题 - 建议在 CI 中分两步:先
buf lint,再buf generate,最后golangci-lint
生成代码永远不该进人工修改流程;一旦你手动改了 _grpc.pb.go,后续 protoc 重生成就会覆盖,而且 lint 错误会变得不可预测。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!











