golangci-lint仅通过plugin机制动态加载自定义linter，要求GOOS/GOARCH匹配、buildmode=plugin、插件名小写无点号、.golangci.yml中用绝对路径声明plugins；Analyzers变量必须为[]*analysis.Analyzer，每个analyzer的Name小写无下划线、Doc非空、Run函数签名正确且报错使用真实AST节点位置。
golangci-lint 怎么加载自定义 linter 的二进制或 plugin
它不认任意 Go 包，只认符合特定签名的 analyzers 变量，且必须编译为可加载形式。直接 go run 或扔个普通命令进去会静默失败。
关键路径只有两条：静态链接进 golangci-lint 二进制（不推荐），或通过 plugin 机制动态加载（官方支持路径）。后者要求：
-
GOOS=linux GOARCH=amd64 go build -buildmode=plugin -o goroutinewithrecover.so ./cmd/goroutine-with-recover—— 必须匹配目标运行环境（CI 通常是 Linux AMD64） - 插件文件名不能含点号或大写，比如
goroutinewithrecover.so合法，goroutine-with-recover.so或GoroutineWithRecover.so会加载失败 -
.golangci.yml中用plugins字段声明路径：plugins: - /abs/path/to/goroutinewithrecover.so
路径必须绝对，相对路径会被忽略 - 插件内导出的
Analyzers变量必须是[]*analysis.Analyzer类型，且每个 analyzer 的Name是小写无下划线（"goroutinewithrecover"✅，"goroutine-with-recover"❌）
为什么自定义 linter 在 IDE 里不报错，但 CLI 运行却没反应
GoLand / VS Code 的 IDE 集成默认不加载 plugins，只跑内置 linter；而 CLI 模式下若未显式启用该插件，或插件路径错误、ABI 不匹配，golangci-lint run 就像没看见它一样。
验证是否真被加载，加 -v 参数运行：
golangci-lint run -v | grep goroutinewithrecover如果没输出，说明加载失败。常见原因：
立即学习“go语言免费学习笔记（深入）”；
- 插件编译时用了不同 Go 版本（如本地用 1.23 编译，CI 用 1.21 运行）→ 报
plugin was built with a different version of package -
GOROOT或GOPATH环境变量在 CI 容器中未继承，导致go/analysis包路径解析异常 - IDE 设置里勾选了 “Use config file”，但
.golangci.yml中没写plugins:块，或路径写成相对路径（如./goroutinewithrecover.so）
自定义 linter 的 Analyzer 必须满足哪些硬性条件
哪怕语法完全正确，只要以下任一条件不满足，golangci-lint 就跳过加载，不报错也不提示。
-
Name字段不能为空字符串，且只能含小写字母和数字，长度 2–20，例如"ctxparam"✅，"ctx-param"❌，"CtxtParam"❌ -
Doc字段不能为空（哪怕只写"check context usage in handlers"） -
Run函数签名必须严格为func(*analysis.Pass) (interface{}, error)，返回值不能是nil, nil（这会被当成成功跳过） - 报错必须用
pass.Reportf(node.Pos(), "...")，其中node得是 AST 中真实存在的节点（如*ast.FuncDecl），传token.NoPos或伪造位置会导致问题不显示在编辑器里
如何让自定义 linter 在 CI 和本地保持行为一致
最稳妥的方式是放弃 plugin 模式，改用「预编译 + vendor」：把自定义 linter 的源码放进项目 internal/linters/，然后在 go.mod 中 replace 到本地路径，并在 .golangci.yml 的 linters-settings 下配置其参数。这样所有环境都走标准 Go 构建链，无 ABI 兼容问题。
但要注意：如果规则本身依赖类型信息（比如判断参数是不是 context.Context），就必须确保 pass.TypesInfo 可用——这意味着不能在 go/ast.Inspect 回调里硬写逻辑，而要老实用 analysis.Analyzer 的 Requires 字段声明依赖 types.Info，否则在 fast 模式下会被跳过。
真正容易被忽略的是：自定义 linter 默认不参与 --fix，除非你在 Run 函数里手动调用 pass.Fset 修改 AST 并写回文件——而 golangci-lint 目前不提供安全的 fix API，强行改容易破坏格式或引入语法错误。
