.golangci.yml必须手动生成并置于go.mod同级目录，命名严格为.golangci.yml；多module项目需各模块单独配置；离线环境须预装所有linter二进制、禁用golint/typecheck、设modules-download-mode: readonly、skip-dirs排除生成代码、output.format设为json。
配置文件必须手动放置且路径严格匹配
内网离线环境无法自动发现或下载配置，.golangci.yml 必须手动生成并放在与 go.mod 同级的项目根目录下——名字不能是 .golangci.yaml、golangci.yml（缺点）、或放在 src/ 子目录里。多 module 仓库中，每个子模块目录都得有自己的一份，父目录配置不继承。
- 用
ls -a | grep golangci确认文件名拼写和隐藏属性 - CI 脚本中必须显式传
--config=.golangci.yml，不能依赖自动查找 - 离线时 YAML 解析失败不会报错，只会静默回退到默认 linter 集（含已弃用的
golint），导致误报或 panic
所有 linter 二进制和依赖必须提前预装
golangci-lint 默认会按需拉取某些 linter 的 Go 包（如 gomodguard_v2），离线环境下这一步必然失败。v2.12.2+ 已修复部分阻塞问题，但仍需确保：golangci-lint 本身及其启用的每个 linter（如 staticcheck、unused）都以静态二进制形式预装在 PATH 中，或通过 go install 在联网机器上提前构建好再拷贝进来。
- 推荐用
go install github.com/golangci/golangci-lint/cmd/golangci-lint@v2.12.2在外网构建，再把$(go env GOPATH)/bin/golangci-lint拷入内网 - 禁用需要动态加载的 linter：必须在
linters.disable显式写["golint", "typecheck"]，后者易因离线缺失go/types相关包而卡住 - 避免使用
gomodguard等依赖实时模块解析的 linter，除非确认其 v2 版本已完全静态化
modules-download-mode 和 skip-dirs 是防卡死关键
离线环境中，任何尝试访问网络或修改 go.sum 的行为都会超时或失败。golangci-lint run 默认可能触发 go list -mod=mod，进而尝试下载缺失模块。必须靠配置堵死这条路。
-
run.modules-download-mode: readonly强制所有模块操作只读，这是离线场景的强制项 -
run.skip-dirs至少包含vendor、testdata、internal/gen—— 自动生成的代码（如pb.go）常含无法解析的 import，引发failed to load program: typechecker error - 若项目含
//go:generate脚本，确保生成物目录已加入skip-dirs，否则errcheck会对proto.Unmarshal类调用误报
output.format 必须选 json 且禁用颜色
离线 CI 环境通常没有 TTY，也不支持 ANSI 颜色码。golangci-lint 默认输出带颜色的终端文本，会被日志系统截断或解析失败。结构化输出必须显式指定且适配下游工具。
-
output.formats只保留一项：format: json+path: report.json；不要混用colored-line-number - 加
output.print-issued-lines: true，否则 JSON 里没源码上下文，调试时无法定位 - CI 中务必加
--out-format=json命令行参数，YAML 里的output.formats在某些旧版中不生效
离线配置最脆弱的环节不是语法，而是“默认行为”——比如 typecheck 默认开启、modules-download-mode 默认非只读、output 默认不结构化。这些地方不显式覆盖，就等于留了网络调用或终端依赖的后门。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
