golangci-lint 不支持全局配置,仅按固定顺序在当前目录及祖先路径查找配置文件,不读取 $HOME 或 /etc 下文件;强行设全局配置会导致项目行为不一致、CI 失败、Go 版本兼容问题。

golangci-lint 没有真正意义上的“全局配置”——它只认当前工作目录或其祖先路径下的 .golangci.yml(或 .golangci.yaml 等),不会自动读取用户主目录或系统级配置文件。强行设全局规则,反而会导致项目间行为不一致、CI 失败、Go 版本兼容问题。
所以别折腾 /etc/golangci.yml 或 $HOME/.golangci.yml,直接用项目级显式配置才是唯一可靠做法。
为什么不能靠环境变量或 GOPATH 设全局配置
golangci-lint 不解析 GOPATH、GOROOT 或自定义环境变量来加载配置;它只按固定顺序查找:.golangci.yml → .golangci.yaml → .golangci.toml → .golangci.json,且仅限当前目录向上遍历到根目录为止。没有 fallback 到家目录的逻辑。
- 试图用
alias golangci-lint='golangci-lint -c $HOME/.golangci.yml'会破坏run.cwd行为,导致go.mod解析失败 - 在 monorepo 中,子模块可能依赖不同 Go 版本或
replace,统一配置会让staticcheck报一堆undefined: xxx - CI 环境通常清空 HOME,这类 alias 完全失效
多项目共用一套规则?用 git submodule 或模板仓库
如果你真需要多个项目保持 lint 规则一致,推荐用可复用的配置片段,而不是“全局”。例如:
- 在独立仓库(如
myorg/golang-lint-config)中维护config.yml,内容只含linters和linters-settings部分 - 各项目通过
git submodule add https://github.com/myorg/golang-lint-config .golangci-config引入 -
.golangci.yml只保留run:配置,并用include:加载子模块:include: [".golangci-config/config.yml"]
- 更新规则时只需
git submodule update --remote,所有项目同步生效
CI/CD 中避免重复写配置的实用技巧
GitHub Actions 或 GitLab CI 里,与其把整段 YAML 塞进 steps,不如用 curl 动态拉取:
立即学习“go语言免费学习笔记(深入)”;
- 确保 CI 的
GO111MODULE=on,否则golangci-lint无法正确 resolve modules - 用
curl -s https://raw.githubusercontent.com/myorg/golang-lint-config/main/config.yml -o .golangci.yml生成配置 - 加
--timeout=2m和--modules-download-mode=readonly,防止因网络或go.sum冲突卡住 - 禁止在 CI 中用
--fix:它可能意外修改生成代码(如pb.go),引发构建失败
include: 或脚本拉配置,run.skip-dirs 和 issues.exclude 仍必须写在项目本地的 .golangci.yml 顶层——它们不支持被 include 文件覆盖。生成代码目录(internal/gen、mocks)、proto 输出路径、vendor 这些,每个项目结构不同,没法统一。


















