Go vet 为什么不默认检查变量遮蔽

因为变量遮蔽并不等于语法错误，也不一定代表程序有 bug。Go 编译器会拒绝未使用的局部变量、类型错误等确定性问题；而 go vet 面向的是“可能有问题”的静态诊断。shadow 分析器会在内层作用域声明同名变量、并且外层变量之后还会被使用时给出提示，但官方说明也承认它可能产生较多误报，所以没有放进默认检查集合。

结论：日常先运行默认的 go vet ./...；确实希望审查遮蔽时，再把 shadow 作为独立的 vet 工具运行，并把它当作需要人工判断的工程规则。

先看清 := 到底遮蔽了什么

最容易踩坑的是循环读文件时的 err。下面的 err 在循环体内由 := 新建，外层函数返回的却仍是另一份变量：

func readAll(r io.Reader) error {
	var err error // 外层错误变量，函数结尾会返回它
	for {
		buf := make([]byte, 1024) // 每轮只负责准备本轮缓冲区
		n, err := r.Read(buf)     // 新建内层 err，可能遮蔽外层 err
		if err != nil {
			if err == io.EOF { // 本轮读取结束，内层 err 只在循环体内可见
				break
			}
			return err // 这里返回的是内层 err
		}
		_ = n // 示例只关注作用域，真实代码应处理读取的数据
	}
	return err // 外层 err 没有被更新，可能仍是 nil
}

但“同名”本身不够构成错误。函数参数、短生命周期的循环变量、只在局部使用的状态，都可能是清晰且合法的命名。编译器也不会因为遮蔽就拒绝代码，因为作用域规则明确，程序仍然可以正确编译。

为什么默认 go vet 不包含 shadow

go vet 默认启用的是相对稳定、误报边界更窄的一组检查，例如格式化参数、结构体标签、不可达代码和部分资源使用问题。它的目标是发现可疑构造，不承诺每条报告都是真错误。

变量遮蔽的难点在于“外层变量之后还会不会被使用”需要结合控制流、作用域和开发者意图判断。过于宽松会漏掉上面的错误，过于严格又会把大量有意的局部命名报告出来。官方 shadow 文档因此把它描述为尚未默认启用的分析器。

所以，运行默认命令没有提示，并不能证明项目绝对没有遮蔽；它只表示默认分析集合没有把这条实验性规则纳入当前结果。

用 -vettool 单独启用 shadow

官方推荐的路径是安装 shadow 命令，再让 go vet 通过 -vettool 使用它。安装和检查可以拆成两个明确步骤：

# 固定到团队选定的 x/tools 版本，避免 CI 每次解析到不同代码
go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@latest

# 用当前 PATH 中的 shadow 运行 ./...，报告只针对这次额外分析
go vet -vettool="$(which shadow)" ./...

如果环境没有把 Go 的安装目录加入 PATH，可以把 which shadow 换成绝对路径。命令成功表示没有报告，不表示所有遮蔽都被证明安全；发现报告时，先看行号和外层变量的后续用途。

把报告变成可执行的修复判断

看到 shadow 报告后，不要机械地把每个变量都改成不同名字。按下面的顺序判断更稳：

1. 确认外层变量是否还要在后面使用。如果外层值在遮蔽点之后完全不再读取，提示往往只是风格噪声。
2. 检查 := 是否真的新建了变量。同一作用域内没有新变量时，应使用 =；跨作用域时，即使左侧有一个新变量，也可能同时创建一份同名局部变量。
3. 优先改名或缩小作用域。对 err 这类高频变量，最清晰的修复通常是让读取结果使用 readErr，或把一次读取封装到更小的函数里。
4. 记录有意遮蔽的理由。如果局部变量确实表达另一种生命周期，把它保持局部并在代码评审中说明，比为了消除提示引入更长、更难读的名字更好。

在 CI 中怎么放置这条检查

建议把默认检查和 shadow 分成两个命令：默认 go vet ./... 作为基础门禁，shadow 作为单独的静态分析任务。这样能在日志中区分“Go 默认诊断失败”和“额外规则需要人工处理”，也方便团队逐步收紧规则。

最后记住三个边界：shadow 不能替代编译器；它不会证明变量命名符合业务意图；它的报告也不等于必须修改。对大型仓库先在报告模式运行，统计真实误报，再决定是否把非零退出纳入合并门禁。

常见问题

默认 go vet 没报错，代码就没有变量遮蔽吗？
不是。默认集合没有启用 shadow，只能说明当前默认分析没有报告问题。

可以给 go vet 直接加一个 shadow 参数吗？
更稳妥的做法是使用官方 shadow 命令和 -vettool，让额外分析器的版本、安装方式和日志都可追踪。

为什么不把 shadow 永久打开？
因为它面对的是意图判断，误报成本可能高于收益。按仓库风险和团队命名规范独立接入，通常比默认阻断所有构建更可控。