自定义 go fix 规则没有生效通常缺少什么声明

旧函数已经改成调用新 API，甚至还写了 // Deprecated:，执行 go fix -inline ./... 却没有任何差异，这时最常漏掉的不是导入包，而是旧声明前那一行精确指令：//go:fix inline。它必须紧邻可迁移的函数、命名常量或类型别名；只有弃用注释不会让 inline fixer 自动改写调用点。

如果你说的“自定义规则”不是声明式内联，而是自己写的 go/analysis Analyzer，那么还要再检查一层：诊断必须携带非空 SuggestedFixes，工具入口要用 unitchecker.Main 注册 Analyzer，并通过 go fix -fixtool=... 运行。只有 Reportf 消息、没有文本编辑建议，go fix 就没有内容可应用。

官方命令说明：https://pkg.go.dev/cmd/go#hdr-Gofix

先判断你写的是哪一种 go fix 规则

我遇到这个问题时，第一反应也是去检查命令参数。后来把两种实现路径分开，定位会快很多：一种是 Go 1.26 起提供的声明式 source-level inliner，另一种是通用的 go/analysis Analyzer。两者都能由 go fix 应用，但“必须声明什么”并不完全相同。

如果旧 API 本身就能用新 API 表达，声明式内联通常成本最低。只有当规则需要跨节点匹配、检查类型或生成更复杂的文本编辑时，才值得写 Analyzer。先选对路径，比反复调整命令行更重要。

旧 API 前必须有精确的 //go:fix inline 指令

下面这个旧函数已经把实现委托给新函数，但仅有弃用注释时，文档工具知道它已弃用，inline analyzer 却没有得到自动迁移授权。补上指令后，调用 OldParse(s) 才能被安全地替换为 Parse(s, DefaultOptions)。

package parse

// Deprecated: 请改用 Parse，并显式传入 DefaultOptions。
//go:fix inline
func OldParse(s string) Result {
	// 旧 API 用新 API 表达，给内联器提供等价替换体。
	return Parse(s, DefaultOptions)
}

这里的拼写和位置都要准确：是 //go:fix inline，不是 // go:fix inline，也不是放在某个普通说明段落里。函数指令放在函数声明前；单个常量可以放在该常量前，常量组也可以在组前统一标记；类型场景要求右侧是别名，而不是新定义的命名类型。

package oldapi

import newapi "example.com/project/v2/api"

//go:fix inline
const DefaultMode = newapi.DefaultMode // 只能内联到另一个命名常量。

//go:fix inline
type Config = newapi.Config // 必须是类型别名，不能写成 type Config newapi.Config。

声明存在仍不改写，要看安全边界

//go:fix inline 不是“强制替换”开关。官方 inliner 会避免改变求值顺序等语义；无法安全约简时，它宁可不建议修改。函数调用发生在该符号自己的专用测试中，或者声明位于 foo.go 而使用点位于 foo_test.go，也可能被保留，因为这些测试本来就是为了验证旧符号。

另一个常见边界是语言版本。Go 官方的 modernizer 会根据 go.mod 的 go 指令或文件的构建约束判断目标代码能否使用较新的语言特性。规则依赖 Go 1.26 能力，而模块仍声明较低版本时，“没有差异”可能是保护行为，不是指令失效。

# 先确认当前工具链是否支持分析框架版本的 go fix
go version

# 查看默认工具包含哪些 fixer，以及 inline 的专用说明
go tool fix help
go tool fix help inline

# 只打印统一差异，不直接修改源文件
go fix -diff -inline ./...

看到空 diff 后，不要立刻移动注释或扩大包范围。先确认待迁移调用是否真的在目标包集合内，再检查它是不是测试保护场景、类型别名是否写成了新类型、常量是否引用另一个命名常量，以及替换是否会改变表达式求值。

复杂规则要在 Diagnostic 里提供 SuggestedFixes

声明式内联解决不了所有问题。例如你要识别特定函数调用，并把它替换成另一段语法，就需要自定义 Analyzer。这里最容易出现的“规则跑了但文件没变”，是只调用了 pass.Reportf：它能产生诊断消息，却没有告诉驱动该改哪段文本。

package replaceold

import (
	"go/ast"

	"golang.org/x/tools/go/analysis"
	"golang.org/x/tools/go/ast/inspector"
	"golang.org/x/tools/go/analysis/passes/inspect"
)

var Analyzer = &analysis.Analyzer{
	Name:     "replaceold",
	Doc:      "把明确可替换的 oldapi.Call 改成 newapi.Call",
	Requires: []*analysis.Analyzer{inspect.Analyzer},
	Run:      run,
}

func run(pass *analysis.Pass) (any, error) {
	insp := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
	insp.Preorder([]ast.Node{(*ast.SelectorExpr)(nil)}, func(n ast.Node) {
		sel := n.(*ast.SelectorExpr)
		if sel.Sel.Name != "Call" {
			return // 只处理目标方法名，避免扩大改写范围。
		}

		pass.Report(analysis.Diagnostic{
			Pos:     sel.Pos(),
			End:     sel.End(),
			Message: "旧调用可迁移到新 API",
			SuggestedFixes: []analysis.SuggestedFix{{
				Message: "替换为 newapi.Call",
				TextEdits: []analysis.TextEdit{{
					Pos:     sel.Pos(),
					End:     sel.End(),
					NewText: []byte("newapi.Call"), // 给 go fix 真正可应用的文本编辑。
				}},
			}},
		})
	})
	return nil, nil
}

示例为了突出 SuggestedFixes，省略了对象类型、导入关系和作用域校验。生产规则不能只按选择器名字替换，还应通过类型信息确认它确实属于目标包，并在需要新增导入时生成完整、不冲突的编辑。一个 SuggestedFix 里的 TextEdit 不能互相重叠，也不能修改其他包的文件。

Analyzer 还要注册进工具并交给 -fixtool

Analyzer 写好以后不会自动加入 go tool fix 的默认套件。还需要一个可执行程序入口，把 Analyzer 交给 unitchecker.Main。这一步相当于声明“这个二进制包含哪些 fixer”。

package main

import (
	"example.com/migration/internal/replaceold"
	"golang.org/x/tools/go/analysis/unitchecker"
)

func main() {
	// 注册自定义 Analyzer，供 go fix 的 -fixtool 协议调用。
	unitchecker.Main(replaceold.Analyzer)
}

# 构建自定义 fixer 二进制，不把临时路径写进源码
go build -o ./bin/projectfix ./cmd/projectfix

# 先通过 -diff 预览 SuggestedFixes 产生的补丁
go fix -fixtool="$(pwd)/bin/projectfix" -diff ./...

# 差异确认无误后，去掉 -diff 应用同一套修复
go fix -fixtool="$(pwd)/bin/projectfix" ./...

按约束逐层排查，别把无差异都归咎于注释

把问题拆成三层后，排查顺序会很稳定。声明层确认工具能否识别迁移目标，修复层确认是否真的生成文本编辑，接入层确认 go fix 运行的是你的工具。

1. 确认工具链：Go 1.26 之前的旧版 go fix 不具备这一套分析框架与声明式内联能力。
2. 确认指令：//go:fix inline 必须精确拼写，并放在支持的声明位置。
3. 确认替换体：旧 API 要能安全地用新 API 表达；类型必须是别名，常量必须引用命名常量。
4. 确认修复建议：自定义 Analyzer 的 Diagnostic 需要非空 SuggestedFixes，编辑区间不能重叠。
5. 确认工具入口：使用 unitchecker.Main 注册 Analyzer，并在命令中明确传入 -fixtool。
6. 确认目标集合：包模式必须覆盖实际调用点；先用 -diff 查看补丁，再决定落盘。

相关问题

只写 // Deprecated: 为什么不够？

// Deprecated: 是文档约定，用来提示使用者；inline analyzer 识别的是独立的 //go:fix inline 指令。两者可以同时存在，但作用不同。

//go:fix inline 可以标记普通命名类型吗？

不能把新定义的命名类型当成可直接替换目标。类型场景要求别名声明，例如 type Old = newpkg.New。

为什么专用测试里的旧 API 调用没有被替换？

官方 inline analyzer 会保留用于直接测试该符号的调用，避免迁移后失去对旧 API 本身的测试覆盖。

自定义 Analyzer 只有一个 SuggestedFix 可以吗？

可以。关键是 Diagnostic 至少携带一个安全、完整的 SuggestedFix；每个修复可以包含一个或多个互不重叠的 TextEdit。

调试时应该直接运行 go fix 落盘吗？

不建议。先加 -diff 查看统一差异，确认包范围和编辑内容，再用同一命令去掉 -diff。这样可以把“规则没触发”和“触发后补丁不对”分开。

这个问题最终可以压缩成一句话：声明式迁移先补 //go:fix inline，自定义分析器则必须补出真正可应用的 SuggestedFixes，并通过 unitchecker 与 -fixtool 接进 go fix。按声明、修复建议、工具接入三层检查，比盲目扩大包范围更容易找到原因。