Go go vet shadow 检查为什么不属于默认 vet

运行 go vet 时没有看到 shadow，不是命令失效，而是刻意的范围划分：Go 内置 vet 只把高置信度、值得默认阻断的问题放进常规检查；变量遮蔽分析由 golang.org/x/tools 单独提供，官方说明也承认它可能产生较多误报，所以没有默认启用。

为什么 go vet 默认不带 shadow

go tool vet help 展示的是 vet 驱动器认识的检查项，例如 printf、copylocks、lostcancel 和 stdversion。其中“可用”与“默认”是两个概念：go test 还会使用一组经过筛选的高置信度检查，避免一个需要人工判断的提示让普通测试门禁突然失败。

shadow 的分析规则是：内层作用域声明了与外层同名、同类型的变量，并且外层变量在内层声明之后还会被引用。它确实能找出错误处理被遮蔽的情况，但同名变量也可能是有意缩小作用域的写法。因此它更适合显式选择，而不是无条件塞进每次 go test。

变量遮蔽为什么会让后续 return 看错值

下面的代码中，if 块里的短变量声明创建了新的 err。块内判断通过后，函数末尾的 return 仍然读取外层 err，这正是 shadow 值得提醒的场景：

package sample

import "errors"

func load() (string, error) {
	var err error
	if useCache() {
		value, err := readCache() // 中文说明：这里的新 err 只属于 if 作用域
		if err != nil {
			return "", err // 中文说明：块内判断使用的是内层 err
		}
		return value, nil
	}
	// 中文说明：离开 if 后，下面仍引用函数级的外层 err
	return "", err
}

func useCache() bool { return true }

func readCache() (string, error) {
	// 中文说明：示例故意返回错误，便于观察两层 err 的区别
	return "", errors.New("cache miss")
}

这个示例里，遮蔽并不一定会造成编译错误，但会增加阅读和维护成本：读者容易以为所有 err 都指向同一个状态。更危险的版本是内层读取失败后没有立即返回，后续逻辑却依赖外层错误变量。修复时通常把内层变量改成 cacheErr，或者直接复用已经存在的变量并明确赋值。

如何单独运行 shadow 并接入 CI

shadow 由 golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow 命令运行。为让本地和 CI 使用同一套分析器，建议固定版本，而不是每次跟随 latest：

# 中文说明：固定 x/tools 版本，避免分析规则随依赖漂移
go run golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@v0.49.0 ./...

# 中文说明：在 CI 中单独运行附加分析，不改变 go test 的基础门禁
go vet ./...
go test ./...
go run golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow@v0.49.0 ./...

如果团队希望把它变成强制门禁，可以把最后一条放进独立的 shadow job，并缓存 Go module 下载结果。不要把“shadow 没有输出”误解成所有遮蔽都不存在；分析器的目标是可能的非预期遮蔽，规则本身不是程序正确性的证明。

什么时候该修复，什么时候只做提醒

看到 shadow 报告时，可以按三项快速判断：第一，内层变量是否与错误、资源句柄或状态结果有关；第二，离开内层后外层变量是否还会参与返回值、重试或清理；第三，这个同名声明是否只是短小且封闭的局部表达式。前两项为“是”时应优先改名或改成显式赋值；只有第三项成立时，才值得考虑保留并写清意图。

最终的职责边界很简单：go vet 负责默认可接受的基础错误检查，shadow 负责额外的可读性和潜在逻辑风险提示。两者可以并存，但不必让一个仍可能误报的分析器替代基础测试。

常见问题

为什么 go tool vet help 能看到检查项，go vet 却不提示 shadow？

因为 vet 驱动器的可用检查项和默认运行集合不同；shadow 还不属于 Go 工具链内置的那组默认分析器。

shadow 能检查所有同名变量吗？

不能。它按作用域、名称、类型和后续外层引用等条件筛选，目标是可能的非预期遮蔽，不是全量同名统计。

把 shadow 放进 go test 会更安全吗？

不一定。它能增加一层提醒，但误报会让测试门禁变得嘈杂。更适合先在独立 CI 任务中观察，再决定是否阻断。