golangci-lint仅加载名为Analyzers的包级变量，类型为[]*analysis.Analyzer，且每个Analyzer需满足：Name全小写无下划线、Doc非空、Run函数有效；还需在.golangci.yml中显式启用并配置.so插件路径。
怎么让 golangci-lint 加载自定义 analyzer
golangci-lint 不会自动识别任意 Go 包里的 analyzer，它只认一种固定格式的插件：导出名为 Analyzers 的变量，类型为 []*analysis.Analyzer，且每个 analyzer 的 Doc 字段不能为空字符串。
常见错误是只写了单个 Analyzer 变量（比如叫 ctxparam），但没包装成切片；或者 Doc 是空字符串或只有空格——这时 golangci-lint 启动时会静默跳过，不报错也不加载，让人以为“编译成功就完事了”，其实根本没生效。
-
Analyzers必须是包级变量，不能在函数里构造 - 名字必须全小写、无下划线（如
goroutinewithrecover，不能是go_routine_with_recover） - 如果 analyzer 依赖其他 analyzer（比如要用
types.Info），得正确填入Requires字段，否则pass.TypesInfo为 nil
编译成 .so 插件的实操要点
golangci-lint v1.50+ 支持直接加载 Go 编译出的 .so 文件，但不是用 go build -buildmode=plugin 就能行——它要求插件必须用和 golangci-lint 相同的 Go 版本、相同构建参数（尤其是 GOOS/GOARCH）编译，否则运行时报 plugin was built with a different version of package xxx。
推荐做法是统一用容器构建：
- 在
Dockerfile中用和 CI 一致的 Go 镜像（如golang:1.23-alpine） - 执行
go build -buildmode=plugin -o goroutinewithrecover.so ./cmd/goroutine-with-recover - 确保
cmd/xxx/main.go里只做一件事：调用singlechecker.Main(Analyzer)并 import 对应 analyzer 包
注意：.so 文件名必须和 analyzer 的 Name 一致（去掉下划线），比如 goroutinewithrecover.so 对应 Name: "goroutinewithrecover"。
如何在项目里启用私有 linter
不能只靠 golangci-lint run 自动发现插件。必须显式配置 .golangci.yml，告诉它去哪找、叫什么名：
linters-settings:
gocyclo:
min-complexity: 15
<p>linters:
enable:</p>
- goroutinewithrecover # 这个名字必须和 analyzer.Name 完全一致
run: plugins:
- ./goroutinewithrecover.so # 路径相对于 .golangci.yml 所在目录
容易踩的坑：
-
plugins路径写错（比如少了个./，变成绝对路径）会导致 “plugin not found” 但错误信息极简，只说 “failed to load plugin” - 启用了 linter 却没配
plugins，它会报unknown linter，而不是“找不到插件” - CI 环境里没把
.so文件传上去，本地能跑，CI 报plugin not found
-
为什么 testdata 测试通过，但集成后不报错
golangci-lint 的 testdata 测试框架（基于 golang.org/x/tools/go/analysis/analysistest）只验证 analyzer 逻辑本身是否触发，不验证插件加载链路。也就是说：你的 run 函数能正确报告 pass.Reportf，不代表它在真实项目中会被调用。
真正要确认是否起作用，得走完整链路：
- 确保
.so已生成且路径正确 - 检查
.golangci.yml里enable和plugins都配对了 - 加
--debug参数运行：golangci-lint run --debug，看输出里有没有Loaded plugin: goroutinewithrecover - 故意写一个触发规则的代码（比如裸
go func() {}()），观察是否真报错
最常被忽略的是：analyzer 的 Run 函数里用了 pass.Pkg.Path() 或 pass.ResultOf，但没在 Requires 里声明依赖，导致生产环境里 pass.TypesInfo 为 nil，整个检查逻辑静默跳过——连 debug 日志都不会打。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
