golangci-lint在CI中必须显式调用并设--issues-exit-code=1，否则因默认仅非零退出码才失败，导致有issue仍显示success；常见原因包括未安装/版本不一致、缺.golangci.yml、命令未捕获退出码。
golangci-lint 不能只在本地跑，CI 中必须显式调用并设为失败阈值，否则等于没开。
为什么 Jenkins 里 golangci-lint 常被跳过或失效
常见现象是：本地 golangci-lint run 报错，但 Jenkins 流水线里却显示 success；或者 lint 结果被当成 warning 不中断构建。根本原因在于 Jenkins 默认不把 lint 输出当错误处理，且未指定退出码策略。
-
golangci-lint默认成功时返回 0，发现 issue 时返回 1 —— 但 Jenkins 的 shell 步骤默认只在非零退出码时标为失败，所以只要命令本身执行成功（哪怕有 100 条 warning），Jenkins 就认为“这步 ok” - 很多 Jenkinsfile 直接写
sh 'golangci-lint run'，没加--fix或--out-format，也没捕获 exit code - 未提前安装
golangci-lint，或版本不一致（比如本地用 v1.57，Jenkins 节点用 v1.42），导致规则行为不同 - 没配置
.golangci.yml提交进仓库，Jenkins 拉取的是空配置，退化为默认规则集（极宽松）
golangci-lint 在 Jenkins Pipeline 中的正确调用方式
核心原则：让 lint 成为门禁（gate），而不是装饰（decoration）。以下是在 Jenkinsfile 中推荐的写法：
- 先确保工具存在：
sh 'curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.57.2'（建议固定版本，避免自动升级引入破坏性变更） - 显式启用失败策略：
sh 'golangci-lint run --timeout=3m --issues-exit-code=1 --fast=false'，其中--issues-exit-code=1是关键，它让任何 lint issue 都触发非零退出码 - 若需忽略部分路径，用
--skip-dirs或--exclude-use-default=false配合.golangci.yml精确控制，不要靠|| true掩盖问题 - 输出结构化结果供后续分析（如集成到 SonarQube）：
golangci-lint run --out-format=json > golangci-report.json
和 go test 一起跑时的顺序与缓存陷阱
很多人把 golangci-lint 和 go test 放在同一个 stage，但顺序和环境影响很大：
立即学习“go语言免费学习笔记（深入）”；
- 必须在
go mod download之后、go test之前运行golangci-lint，否则可能因依赖未下载完而报cannot find package类错误 - Jenkins 节点若复用 workspace，旧的
go/pkg缓存可能导致 lint 误报（比如残留了已删除的 vendor 包引用），建议加sh 'go clean -cache -modcache'或启用cleanWs()插件 - 不要在
golangci-lint命令里加--fix自动改代码 —— Jenkins 是只读环境，且自动修改会污染 git 工作区，导致后续git diff异常 - 如果项目用了
//go:embed，注意golangci-lintv1.54+ 才完整支持，低版本会漏检 embed 相关规则（如gochecknoglobals）
真正难的不是装上 golangci-lint，而是让它每次都在干净、一致、可审计的上下文中运行 —— 这要求你明确控制 Go 版本、lint 版本、模块缓存、配置文件来源，以及它在整个流水线中的精确位置。
