golangci-lint不是golint升级版，而是集成staticcheck、errcheck等linter的调度平台；golint已于2021年归档，其命名警告非golangci-lint默认行为，且v2起格式化（fmt）与检查（run）已彻底分离。
golangci-lint 不是 golint 的升级版，而是完全不同的工具定位
很多人以为 golangci-lint 是 golint 的“增强版”，实际它根本不是——golint 已于 2021 年归档停更，而 golangci-lint 是一个集成平台，本身不实现任何检查逻辑，只调度和聚合其他 linter（比如 staticcheck、errcheck、govet）。你看到的“报错”，99% 来自它背后启用的具体检查器，不是 golangci-lint 自己写的。
常见误判现象：
- 把
golint的命名风格警告（如don't use ALL_CAPS in Go names）当成golangci-lint的默认行为，其实默认配置里golint是禁用的 - 在 CI 里只跑
golangci-lint run却没启用errcheck，结果db.QueryRow(...).Scan()忘记检查 error 也没被拦住 - 看到
unused报错就以为是代码写错了，其实是golangci-lint默认启用了该检查器，而golint根本不报这类问题
格式化和静态检查在 v2+ 版本中彻底分离
v2.0.0（2025年3月24日发布）起，golangci-lint 明确拆出 fmt 子命令专管格式化，和 run 命令各司其职。这不是功能叠加，而是职责划界。
迁移时容易踩的坑：
立即学习“go语言免费学习笔记（深入）”；
- 旧脚本里用
golangci-lint run --fix试图自动修复格式问题，现在会失败：v2+ 中--fix只对支持 auto-fix 的 linter（如goimports）生效，且仅限语义级修复，不处理缩进/换行等纯格式问题 - 配置文件里写了
linters: enable: [gofmt]，但没配linters-settings.gofmt，导致gofmt实际未启用——必须显式开启并确认是否在run阶段运行 - CI 流程仍用
gofmt -l .+golangci-lint run两步，是对的；但如果改成只跑golangci-lint fmt就漏了run的逻辑检查，质量防线直接塌一半
结构体初始化检查器从 exhaustruct 切到 exhaustruct_v5 的配置陷阱
v2.13.0（2026年8月19日）起，exhaustruct 被标记为废弃，必须改用 exhaustruct_v5。这不是简单改个名字的事，参数体系已重构。
典型配置断裂点：
- 旧配置用
include: ["Config", "Options"]控制检查范围，新版本拆成include: ["Config", "Options"]（类型匹配）和mode: "explicit"（检查模式）两个独立字段，少设一个就退化为全量检查 -
exhaustruct_v5默认只检查导出结构体，如果项目里大量使用未导出配置结构体（如type dbConfig struct { ... }），不加check-unexported: true就等于没开这个检查 - 升级后突然冒出大量新告警，别急着 suppress，先确认
skip-dirs是否仍包含generated：protobuf 或 SQLC 生成的结构体若被误扫，exhaustruct_v5会因字段缺失狂报错
新手不该直接上 golangci-lint，IDE 内置检查才是学习入口
golangci-lint 是给稳定项目守门的，不是给初学者纠错的。它默认启用的 unused、errcheck、staticcheck 会把 var x int、fmt.Println("hello") 全标红，掩盖真正该学的语法和流程。
更务实的做法：
- 先用 Goland / VS Code 的 Go 插件，只开
Unused import、Unreachable code、Shadowing of variable这几项，实时反馈、修复明确、不依赖配置 - 等能写出带测试、有模块划分、可本地跑通的微服务后，再引入
golangci-lint，且初始配置要主动禁用高噪声项：disable: ["unused", "deadcode", "structcheck"] - CI 中首次接入时，先用
--issues-exit-code=0收集基线问题，而不是一上来就--issues-exit-code=1卡构建——否则团队第一反应是删配置，不是改代码
最常被忽略的一点：golangci-lint 的配置生效与否，不能只看 .golangci.yml 里有没有某行，得用 golangci-lint help linters 查当前启用列表，再用 golangci-lint run --debug 看实际加载了哪些检查器——很多“配置了却没生效”的问题，根源都在这里。
