.golangci.yml必须与go.mod同级且严格命名，多module项目需各目录单独配置，CI中须显式指定--config，YAML语法错误会导致静默退回到默认linters。
golangci-lint配置文件名和位置必须严格匹配
配置不生效的首要原因不是内容写错，而是文件根本没被读到。.golangci.yml必须与go.mod同级目录；写成.golangci.yaml、golangci.yml（缺点）、或放在src/、config/下，golangci-lint都会直接忽略。
多 module 项目中，每个 module 目录都得单独放一份.golangci.yml——根目录的配置不会向下继承。CI 脚本里如果只写golangci-lint run，它大概率在子目录执行且找不到配置，必须显式加--config=.golangci.yml。
- 用
ls -a | grep golangci确认文件名拼写（注意是点开头 + yml 小写） - 运行前先
pwd和ls go.mod，确保当前路径下存在go.mod - VS Code 的 Go 插件默认可能缓存旧配置，需手动勾选「使用配置」并填对路径
YAML语法错误会导致配置静默失效
缩进错位、冒号后少空格、用了 Tab 替代空格、顶层字段嵌套错层——这些都不会报错，而是让golangci-lint退回到默认启用集（仅govet、errcheck等约10个），完全不加载你写的staticcheck或unused。
典型误配：linters-settings被缩进成linters的子项，或run和linters看似平级，实际缩进多了一格。
立即学习“go语言免费学习笔记（深入）”；
- 所有顶层字段（
run、linters、linters-settings、output）必须顶格，彼此平级 -
linters.enable是列表，每项前必须是-（短横+空格），不能漏空格或换行错位 - 用
yamllint .golangci.yml提前验证基础语法（需pip install yamllint） - 复制网上示例时小心不可见字符（如全角空格、Zero Width Space）
配置生效但没效果？检查 linter 启用逻辑
装完golangci-lint ≠ 自动查出弃用 API、恒真判断、未使用变量等问题。默认只开govet和errcheck，staticcheck、unused、gosimple这些真正暴露深层缺陷的检查器，默认是关闭的。
常见错误：只启用了govet和errcheck，结果上线后才发现time.Now().Unix() > 0这类SA4006问题一直没被拦截。
- 最小有效组合建议直接写死：
enable: [govet, errcheck, staticcheck, unused, gosimple] - 显式禁用过时工具：
disable: ["golint"]（注意大小写，不是golint） -
staticcheck若需关掉某条规则（如SA1019），须在linters-settings.staticcheck.checks下配，不要靠disable全局关掉 - 别碰
dupl和lll——前者阈值难调、易误报，后者纯属风格偏好，不该卡 CI
output.formats 和 --out-format 必须显式对齐
即使.golangci.yml里写了format: github-actions，如果命令行没加--out-format=github-actions，golangci-lint仍走默认终端输出，CI 就收不到结构化报告。
output.formats只控制golangci-lint run --out-format=xxx时的输出行为，不参与自动发现流程。GitHub Actions 报告没标红、Jenkins 显示 0 issues，往往卡在这一步。
-
format: json适合写入文件后由脚本消费，但要加print-issued-lines: true才带源码上下文 -
format: github-actions专为 GitHub Actions 设计，生成::error file=::格式，但它不支持多个 format 混用 -
max-issues-per-linter: 0（不限制）比默认50更稳妥，避免截断深层问题 -
exclude-rules必须放在issues下才生效；误写在linters-settings里，规则完全不触发
配置热更新本身不成立——golangci-lint是静态分析工具，不监听文件变化。所谓“热更新”，实际是改完.golangci.yml后手动触发golangci-lint run，而最容易被忽略的，就是每次执行时是否真的加载了你刚改的那一份配置。
