golangci-lint在GitLab CI中“静默通过”根本原因是默认exit code为0、未指定--out-format导致日志不可见、未设--config=.golangci.yml且无--issues-exit-code=1，必须组合使用--issues-exit-code=1 --out-format=colored-line-number --timeout=2m --config=.golangci.yml才真正生效。
直接在 .gitlab-ci.yml 里加一个 lint 阶段就能跑，但默认不失败、不报错、不阻断合并——必须显式配置退出码和检查逻辑，否则等于没用。
为什么 golangci-lint 在 GitLab CI 里经常“静默通过”？
常见现象是：本地 golangci-lint run 报一堆 warning，CI 却显示 job passed；或者改了代码触发流水线，lint 结果根本没出现在日志里。
根本原因有三个：
-
golangci-lint默认 exit code 是 0（成功）即使发现 issue，GitLab CI 只看 exit code 判断 job 成败 - 没指定
--out-format或日志级别，输出被截断或格式混乱，CI 日志里看不到具体哪行错了 - 没加
--fast或缓存机制，每次都要重装 linter，拖慢流水线且易因网络失败
golangci-lint run 必须带哪些参数才真正生效？
只写 golangci-lint run 是无效的。关键参数要组合使用：
立即学习“go语言免费学习笔记（深入）”；
-
--issues-exit-code=1：让有 issue 时返回非 0 码，强制 job 失败 -
--out-format=github-actions或--out-format=colored-line-number：前者兼容 GitLab 的 annotations（自动标出文件/行），后者确保日志可读 -
--timeout=2m：防卡死，尤其在大型模块里 -
--config=.golangci.yml：显式指定配置文件路径，避免 fallback 到默认行为
示例命令：
golangci-lint run --issues-exit-code=1 --out-format=colored-line-number --timeout=2m --config=.golangci.yml
如何避免每次重装 golangci-lint？
GitLab Runner 默认不保留二进制，每次 job 都从头 curl 或 go install，既慢又不可靠。
推荐两种稳定做法：
- 用预装镜像：基于官方
golang:1.23-alpine，提前go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.57.2构建自定义镜像，CI 中直接image: my-registry/golang-lint:1.23 - 用 cache：在
.gitlab-ci.yml中启用cache:，把$HOME/go/bin/golangci-lint缓存到key: golangci-bin，首次安装后后续 job 直接复用
注意：不能缓存整个 $HOME/go，因为 go mod download 和 golangci-lint 二进制生命周期不同，混在一起容易冲突。
怎么让 lint 失败真正阻断 MR 合并？
仅 job 失败还不够。GitLab 默认允许手动重试或忽略，必须配合两个设置：
- 在
.gitlab-ci.yml的 lint job 下加rules:块，限定只对main、develop分支和 MR 源分支运行，避免污染 feature 分支调试 - 在 GitLab 项目 Settings → Merge Requests → Merge checks 中勾选 “Pipelines must succeed”，并设为 “All status checks must pass”
这样，MR 页面会明确显示 lint job 状态，不通过就点不了 Merge 按钮。
真正容易被忽略的是：.golangci.yml 里如果用了 run: skip-dirs 或 exclude-rules，而这些路径恰好包含新提交的文件，lint 就会跳过——表面通过，实则漏检。每次更新配置后，建议在本地用 golangci-lint run --no-config --debug 看实际扫描范围。
