golangci-lint安装后需满足三前提才生效：①当前目录含go.mod；②工作路径为模块根目录；③Go版本≥1.16；配置文件必须为.golangci.yml、与go.mod同级、缩进用空格，否则报“no Go files”或配置静默失效。
想在Go项目中快速启用静态代码检查却卡在golangci-lint安装失败、配置不生效或报错“no Go files”？这通常是因为环境路径没对齐、Go module未启用，或配置文件放错了位置。
安装golangci-lint（推荐go install方式）
用go install命令安装最新稳定版，避免二进制下载权限/平台适配问题。
执行：go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
安装完成后，终端需重启或运行source ~/.zshrc（macOS）或source ~/.bashrc（Linux）让$GOPATH/bin加入PATH——否则运行golangci-lint --version会提示command not found。
立即学习“go语言免费学习笔记（深入）”；
验证是否成功：golangci-lint --version，输出类似golangci-lint has version v1.56.2 built from ...即为正常。
运行前必须确认的3个前提条件
① 当前目录下存在go.mod文件。golangci-lint默认只扫描module-aware模式下的包，【没有go.mod就直接报no Go files error】，不会退回到GOPATH模式。
② 执行命令时，终端工作路径必须是模块根目录（即含go.mod的那层），不能在子目录如./internal/service里直接运行——它不会向上递归查找go.mod。
③ Go版本需≥1.16（推荐≥1.19）。低于1.16时即使有go.mod，go list -json ./...也会因不支持-modfile等参数导致内部调用失败。
本地配置文件正确写法与加载优先级
方法一：项目根目录放.golangci.yml（最常用）
内容示例：
run: timeout: 5mlinters-settings: golint: min-confidence: 0.8
注意：YAML缩进必须用空格，不能用Tab；顶层字段名如run、linters-settings大小写敏感，写成Run或LintersSettings将被静默忽略。
方法二：用-c指定任意路径的配置文件：golangci-lint run -c ./config/.my-lint.yml
方法三：通过环境变量GOLANGCI_LINT_CONFIG指定，优先级高于项目内文件。
常见报错速查与修复
“no Go files”：先ls go.mod确认存在，再pwd看是否在模块根目录；若用VS Code插件触发，检查插件设置里是否启用了"golangci-lint.runOnSave": true且工作区已打开模块根目录。
“failed to load analysis result” 或 “context deadline exceeded”：大概率是某linter（如revive或nilness）在大项目中分析超时，可在.golangci.yml中加run: timeout: 10m，或临时禁用耗时linter：linters-settings: revive: enabled: false。
修改了配置但没生效：golangci-lint会缓存结果，默认开启issues-cache，执行golangci-lint cache clean再重试。
