golangci-lint 输出需匹配使用场景：output.formats 必须显式设为 json、github-actions 或 checkstyle 等机器可解析格式，issues 中 max-issues-per-linter 等参数需调优，CI 失效常因未传 --out-format、路径错误或退出码被忽略。
golangci-lint 的输出格式和检查报告不是“配完就能用”，关键在 output.formats 和 issues 两处配置是否匹配实际使用场景——尤其当集成到 CI（如 GitHub Actions）或 IDE 时，错配会导致报告丢失、行号错乱、甚至检查失败不中断流程。
output.formats 配置决定报告能不能被工具识别
默认只输出带颜色的终端文本，这对人眼友好，但对机器解析（比如 CI 解析告警、编辑器跳转错误）完全无效。必须显式声明结构化格式：
-
format: json是最通用的选择，适合写入文件后由脚本消费，但注意：JSON 输出默认不包含源码上下文（print-issued-lines: true必须手动开启） -
format: github-actions专为 GitHub Actions 设计，会生成::error file=...::格式，CI 才能自动标注 PR 中的问题行；但它不支持同时输出多个 format，也不能和json混用 -
format: checkstyle主要用于 Jenkins 或 SonarQube，但它的路径字段是相对项目根目录的，如果golangci-lint run在子目录执行，路径会错位 - 所有 format 的
path字段必须是具体路径（如report.json）或stdout；写成-或留空会静默失败
issues 配置影响报告是否“看得见问题”
很多人配了 output.formats 却收不到预期报告，其实是 issues 级别过滤太严：
-
max-issues-per-linter: 50是默认值，单个 linter（如staticcheck）超过 50 条就截断，容易漏掉深层问题；CI 中建议设为0（不限制）或一个足够大的数 -
max-same-issues: 5会合并重复模式的报错（比如同一行多次未处理 error），设得太小会让真实问题被折叠，本地调试时建议关掉（设为0） -
exclude-rules放在issues下才生效；如果误写在linters-settings里，规则完全不触发 - 想忽略某个文件的全部问题？用
exclude-rules+ 正则匹配path；想忽略某类问题文本？正则匹配text；二者逻辑是“且”，不是“或”
CI 中报告失效的三个高频原因
GitHub Actions 报告没标红、Jenkins 显示 0 issues，往往不是配置写错了，而是环境或命令层面卡住了：
立即学习“go语言免费学习笔记（深入）”；
- 没加
--out-format=github-actions参数：即使.golangci.yml里写了github-actions格式，命令行不显式指定，它仍走默认 terminal 输出 - 运行路径不对：
golangci-lint run ./...中的./表示当前目录，但 CI 工作目录可能是/home/runner/work/repo/repo，而配置里skip-dirs: vendor是相对项目根的，路径错位会导致跳过失效 - 退出码被吞：CI 脚本里用了
|| true或set +e，即使golangci-lint因发现问题返回非零码，流程也不会中断
本地开发与 CI 的输出策略必须分开
同一份 .golangci.yml 很难兼顾本地快速反馈和 CI 严格报告。推荐用环境变量或配置继承拆分：
- 本地用
golangci-lint run --out-format=colored-line-number，配合print-issued-lines: true看上下文，快且直观 - CI 用
golangci-lint run --out-format=github-actions --timeout=3m，不依赖配置文件里的output.formats，避免配置污染 - 真要共用配置，把 CI 专用项（如
issues.max-issues-per-linter: 0）抽到.golangci.ci.yml，用--config=.golangci.ci.yml覆盖主配置
真正麻烦的不是写对 YAML，而是不同场景下输出目标（人 / CI / IDE）、路径上下文、退出行为三者必须咬合。少一个对齐点，报告就变成“看起来跑完了，其实什么都没发生”。
