golangci-lint配置不生效的典型表现是运行golangci-lint run无报错却漏检未使用变量、弃用API等关键问题，根本原因是默认仅启用govet和errcheck，staticcheck、unused等核心检查器未显式启用，且.golangci.yml必须与go.mod同级、命名严格为点开头yml后缀，多module项目需各module单独配置，CI和IDE中均须显式指定--config=.golangci.yml才生效。
golangci-lint 配置不生效的典型表现
运行 golangci-lint run 没报错，但明明写了未使用的变量、调用了已弃用函数，却完全没提示——这不是工具没装好，而是配置根本没加载。它默认只开 govet 和 errcheck，staticcheck、unused 这些真正揪逻辑问题的检查器全关着。
常见失效原因：
-
.golangci.yml文件名写成.golangci.yaml或golangci.yml（少个点） - 文件放在项目根目录，但
go.mod在cmd/或internal/子目录里——必须和go.mod同级 - 多 module 项目（比如 monorepo），只在根目录放一份配置，而
golangci-lint不会向上查找，每个 module 都得单独放一份 - CI 脚本直接跑
golangci-lint run，没加--config=.golangci.yml参数 - VS Code 的 Go 插件没勾选「Use config file」或路径填错，仍走缓存规则
必须启用的 5 个核心 linter 及最小配置
别贪多，先配这五个：它们误报率低、覆盖真实风险高，且彼此冲突少。
.golangci.yml 示例（与 go.mod 同目录）：
立即学习“go语言免费学习笔记（深入）”；
linters-settings:
revive:
rules:
- name: exported
disabled: true
staticcheck:
checks: ["all"]
linters:
- govet
- errcheck
- staticcheck
- unused
- revive
run:
skip-dirs:
- generated
- migrations
issues:
exclude-rules:
- path: "_test\.go"说明：
-
govet查死循环、类型不匹配、变量 shadowing 等基础语义问题 -
errcheck强制处理 error，避免_ = foo()这类静默失败 -
staticcheck报SA1019（调用弃用 API）、SA4006（明显死循环）等硬伤 -
unused发现未引用的变量、函数、import，清理技术债务最直接 -
revive替代已废弃的golint，支持禁用_ = xxx忽略 error 这类危险写法 - 别碰
dupl（重复代码）和lll（行长限制）——前者阈值难调易误报，后者纯属风格偏好，不该卡 CI
Go Modules 代理与校验和配置必须显式设置
国内环境不配代理，go mod download 会卡住或超时；不设 GOSUMDB，可能因校验失败导致依赖拉不下来或编译中断。
执行以下命令（永久生效）：
macOS/Linux：
在 Golang 中使用 samber/hot 进行内存缓存，支持 LRU、LFU、TinyLFU、W‑TinyLFU、S3FIFO、ARC、TwoQueue、SIEVE、FIFO 等淘汰算法，提供 TTL、缓存加载器及分片功能。
go env -w GO111MODULE=on go env -w GOPROXY=https://goproxy.cn,direct go env -w GOSUMDB=sum.golang.org
Windows PowerShell：
$env:GO111MODULE="on"
$env:GOPROXY="https://goproxy.cn,direct"
$env:GOSUMDB="sum.golang.org"
[Environment]::SetEnvironmentVariable("GO111MODULE", "on", "Machine")
[Environment]::SetEnvironmentVariable("GOPROXY", "https://goproxy.cn,direct", "Machine")
[Environment]::SetEnvironmentVariable("GOSUMDB", "sum.golang.org", "Machine")验证是否生效：
go env GOPROXY 应输出 https://goproxy.cn,direct
go env GOSUMDB 应输出 sum.golang.org
注意：GOPROXY 值末尾的 ,direct 很关键——它表示当代理无法提供模块时，回退到直接从源拉取，避免私有模块被拦截。
结构体绑定配置比 viper 更可控
viper 默认开启 viper.AutomaticEnv()，但没设前缀时会把所有 key 全映射成大写环境变量（如 db.port → DB_PORT），而你可能只想绑定 APP_* 开头的变量；更麻烦的是 viper.Get("xxx") 返回 interface{}，类型错误只能运行时报，IDE 无法跳转、无字段提示。
推荐做法是定义结构体 + mapstructure.Decode：
type Config struct {
DB struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
} `mapstructure:"database"`
}
var cfg Config
if err := mapstructure.Decode(rawMap, &cfg); err != nil {
return err
}好处：
- 类型安全：编译期就能发现字段名拼错、类型不匹配
- IDE 友好：字段可跳转、有自动补全
- 可单元测试：传入不同
map[string]interface{}即可覆盖各种配置场景 - 无全局状态：每个 test case 互不影响
真正容易被忽略的是：配置解析后必须做显式校验，比如检查 cfg.DB.Port > 0，否则空配置也能通过解码，直到运行时连不上数据库才暴露。
