golangci-lint配置生效需严格遵循三要素耦合：--out-format命令行参数优先于配置文件output.formats；issues相关配置必须置于issues:一级字段下；linters-settings中参数仅对已启用的linter生效，且字段层级错位将导致静默失效。
golangci-lint 不是配完 .golangci.yml 就算完事——进阶用户真正卡点的地方，在于输出格式、问题过滤逻辑、linter 行为定制三者的耦合关系。
为什么 --out-format=github-actions 必须显式加在命令行里
即使 .golangci.yml 的 output.formats 已设为 github-actions，CI 中仍可能无报错标注。因为 golangci-lint 会优先以命令行参数为准，配置文件里的 format 只在没传 --out-format 时才生效。GitHub Actions 的 ::error 注释机制只认标准输出流里的特定字符串，终端彩色文本（默认行为）完全不触发 CI 标注。
- 本地调试时可加
--out-format=github-actions配合2>&1 | head -n 5快速验证输出是否含::error前缀 - CI 脚本中不要依赖配置文件自动生效，始终显式传参：
golangci-lint run --out-format=github-actions - 多个 format 无法共存，
output.formats列表里写多个只会用第一个；想同时输出 JSON 和 GitHub Actions？得跑两遍命令
issues 下的 max-issues-per-linter 和 exclude-rules 不是写在哪都管用
这两个配置项只有放在 issues: 一级字段下才生效。如果误塞进 linters-settings: 或顶层，它们会被静默忽略——你改了配置却没效果，大概率是这里错了。
-
max-issues-per-linter: 0在 CI 中必须设为 0，否则像staticcheck检出超 50 条就截断，深层问题直接消失 -
exclude-rules是“且”逻辑：要同时匹配path正则和text正则才忽略，不是满足其一就行 - 想忽略整个
internal/目录？别只写path: "internal/.*"，得补上text: ".*"，否则不生效
linters-settings 里改 govet 或 staticcheck 参数前先看它是否被禁用
很多团队在 linters.disable 里关掉了 govet，但又在 linters-settings.govet 下调参数——这毫无意义，设置不会加载。反过来，如果启用了 govet 却没配 enable-all: true，它默认只开几个子检查，大量有用规则（如 printf、shadow）根本不会跑。
- 查当前启用的 linter 列表：运行
golangci-lint help linters，带[enabled]标记的才是真生效的 -
govet推荐配法：enable-all: true+disable: ["fieldalignment"]，比手动逐个enable更稳 -
staticcheck的checks字段只接受 ID（如"SA1019"），不接受描述文本；ID 错一个字符就静默失效
print-issued-lines: true 不只是“显示代码行”，它影响 JSON 输出结构
这个选项控制是否在报告里嵌入源码上下文。对人眼友好的终端输出里它只是多几行代码，但在 format: json 下，它会让每个 issue 多出 code 字段（含高亮行和上下文），否则 JSON 里只有 line 和 column，下游脚本没法做精准定位或 diff 分析。
- CI 中生成 JSON 报告供后续工具消费时，
print-issued-lines: true是刚需 - 但开启后 report.json 体积明显增大，大型项目建议只在需要时打开，平时关掉
- 该字段属于
output:下的配置，不是run:或issues:，放错层级会无效
最常被跳过的细节是：golangci-lint 的配置解析顺序严格分层，字段位置错一位，整段配置就成摆设。与其反复试错，不如每次改完用 golangci-lint run --config=.golangci.yml --no-config --help 看实际加载的配置快照。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
