output.formats 必须显式指定,否则 CI/IDE 等工具无法解析;常见格式有 json(需配 print-issued-lines: true)、github-actions(专用于 PR 标注)、checkstyle(路径需注意相对根目录);--out-format 命令行参数优先级最高,且仅 run 命令生效,fmt 不支持该配置。

output.formats 必须显式指定,否则机器无法解析
golangci-lint 默认输出带颜色的终端文本,人眼可读,但 CI、IDE、Jenkins 等工具完全无法识别。不设 output.formats,就等于没生成报告。
常见错误现象:GitHub Actions 里没标红、Jenkins 显示 0 issues、本地脚本读不到 JSON 字段——十有八九是漏了这一步。
-
format: json最通用,适合写入文件后由 Python/Shell 脚本消费;但注意:必须配print-issued-lines: true才能带源码上下文 -
format: github-actions专为 GitHub PR 标注设计,输出形如::error file=main.go,line=42::unused variable "x";但它不支持多 format 并存,也不能和json混用 -
format: checkstyle用于 SonarQube 或 Jenkins,但它的file字段路径是相对于项目根目录的;若在子目录执行golangci-lint run ./sub,路径会错位成sub/main.go,导致报告失效 -
path字段不能写-或留空,必须是具体路径(如report.json)或stdout,否则静默失败
issues 配置不当会让报告“有结果却看不见”
即使 output.formats 写对了,报告仍可能被截断、折叠或过滤掉——问题常出在 issues 块。
-
max-issues-per-linter: 50是默认值,一旦某个 linter(如staticcheck)报出 51 条,第 51 条起全丢;CI 中建议设为0(不限制) -
max-same-issues: 5会合并相同模式的重复告警(比如同一行连续 10 次未处理 error),设太小会让真实问题被掩盖;调试时建议设为0 -
exclude-rules必须放在issues下才生效;若误写进linters-settings,规则彻底不触发 - 忽略某文件?用正则匹配
path;忽略某类报错文本?用正则匹配text;二者是“且”关系,不是“或”
--out-format 命令行参数优先级高于配置文件
很多人在 .golangci.yml 里写了 github-actions 格式,CI 里却还是输出彩色文本——因为没在命令行加 --out-format=github-actions。
立即学习“go语言免费学习笔记(深入)”;
golangci-lint 的行为逻辑是:命令行参数 > 配置文件 > 默认值。配置文件里的 output.formats 只影响 golangci-lint run 的默认行为,但 CI 脚本中若没显式传参,它仍走终端格式。
- GitHub Actions 示例:
golangci-lint run --out-format=github-actions - 写入 JSON 文件示例:
golangci-lint run --out-format=json --out-file=report.json -
--out-file和output.formats.path是两套机制,推荐统一用后者,避免混淆
fmt 命令不参与 output.formats 配置
格式化(golangci-lint fmt)和静态检查(golangci-lint run)是两个独立命令,各自有不同配置域。output.formats 只对 run 生效,对 fmt 完全无效。
想让格式化也输出结构化结果?不行。fmt 命令只做修改文件或打印差异(-d),不生成报告。如果需要“哪些文件被改了”,得靠 shell 捕获 stdout 或用 git status 判断。
-
golangci-lint fmt -d ./...输出 diff,适合人工确认 -
golangci-lint fmt ./...直接改写文件,无返回内容 - 不要试图在
output.formats里给 fmt 加json,它会忽略
output.formats 和 issues 是双保险,缺一不可;而命令行参数是最后一道闸门,CI 脚本里漏掉 --out-format 就等于前功尽弃。


















