output.formats必须显式设为json、github-actions或checkstyle等机器可解析格式，否则默认带颜色的终端文本无法被CI、IDE或脚本解析；issues中max-issues-per-linter等参数需调优，否则问题被截断或过滤导致报告为空。
output.formats 必须显式声明结构化格式
golangci-lint 默认输出带颜色的终端文本，stdout 上看着清晰，但 CI、IDE 或脚本完全无法解析。不配 output.formats，就等于没导出——不是“导出失败”，而是“根本没生成可解析内容”。
常见错误是只写了一行 format: json 却漏掉 path，结果静默失败；或把 path 写成 -（以为代表 stdout），实际会跳过写入。
-
format: json最通用：适合后续用 jq 或 Go 脚本消费，但必须加print-issued-lines: true才带源码上下文 -
format: github-actions专用于 GitHub Actions：生成::error file=...::格式，PR 中自动标红问题行；不能和其它 format 共存 -
format: checkstyle适配 Jenkins/SonarQube：注意它的file字段是相对项目根路径的，若在子目录执行golangci-lint run ./sub，路径会错位
issues 配置决定报告里“有没有问题”
很多人配完 output.formats 却收不到预期条目，其实是 issues 层级过滤太狠，把问题直接拦在了输出前。
-
max-issues-per-linter: 0—— CI 中务必设为 0（不限制），否则staticcheck超过默认 50 条就截断，深层问题消失 -
max-same-issues: 0—— 本地调试建议关掉合并，避免同一类错误（如多处if err != nil { return }未处理）被折叠成一条 -
exclude-rules必须放在issues:下，写在linters-settings:里完全不生效
路径与执行范围不匹配导致报告为空
report.json 文件生成了，但里面是空数组或只有统计信息？大概率是扫描范围没覆盖到目标文件。
立即学习“go语言免费学习笔记（深入）”；
- 传目录时记得加
/后缀：用golangci-lint run ./src/才递归，./src只扫该目录下一级 - 不能混用参数：
golangci-lint run main.go ./pkg/是非法的，单个文件和包路径不能同时出现 - 所有被检查的
.go文件必须属于同一个 Go 包，跨包混合传参会跳过部分文件 - 确认
run:skip-dirs没误删了你真正想检查的目录，比如写了-gen/却忘了gen目录里其实有手写逻辑
CI 中忽略退出码会让报告“失效却无感知”
GitHub Actions 里跑完 golangci-lint run --out-format=github-actions，日志里明明有 ::error，但 PR 检查仍显示通过——八成是 step 没设 fail-fast 或用了 || true。
- 确保命令末尾没加
|| true、set +e等掩盖退出码的操作 - GitHub Actions 中推荐显式写
if: ${{ always() }}控制后续步骤，而不是靠 shell 抑制错误 -
--fix参数慎用于 CI：它可能改写代码但不提交，造成状态不一致；建议只在 pre-commit 或本地使用
最易被忽略的是：JSON 输出默认不带源码行内容，print-issued-lines: true 这个开关不在顶层，而在 output: 下，且必须和 format: json 在同一组配置块里——少缩进一个空格，它就不生效。
