测试缓存未失效时输入文件依赖的处理

先判断：旧结果为什么会被复用

测试读取了配置、JSON 或模板文件，文件已经变更，go test ./... 却仍显示 (cached)。这通常不是“Go 完全不看输入文件”，而是测试依赖没有以 Go 测试缓存能够观察的方式进入缓存键。

官方说明给出的关键边界是：在包列表模式下，Go 会缓存成功的包测试结果；测试打开模块内文件或读取环境变量时，后续只有这些文件和变量保持不变才会匹配旧结果。反过来，模块外动态文件、子进程间接读取、网络响应或没有显式暴露的生成数据，不应默认认为一定能让结果缓存自动失效。

稳定 fixture 放进模块并由测试直接读取；模块外输入要么显式传入内容摘要，要么用 -count=1 禁用测试结果缓存。不要把反复清空整个构建缓存当成长期方案。

缓存命中并不只看测试代码

测试结果缓存先根据测试二进制和命令行中的可缓存参数形成测试身份，再结合上次测试记录的文件和环境变量计算输入身份。两部分都匹配时，Go 才会重放之前的成功输出。

这里有三个容易忽略的规则：

• 只有成功的包测试结果会被缓存，失败结果不会成为下一次的成功命中。
• 结果缓存用于包列表模式，例如 go test .、go test ./...；不带包参数的裸 go test 属于本地目录模式，不使用该结果缓存。
• -run、-short、-timeout、-v 等属于可缓存参数；-count=1 是官方建议的显式禁用方式。

先用缓存调试信息确认依赖有没有被记录

不要第一步就执行 go clean -cache。先打开测试缓存决策日志，确认当前命令是否尝试命中缓存，以及命中或跳过的原因。

# 输出测试结果缓存的复用决策，信息量适中
GODEBUG=gocachetest=1 go test ./...

# 输出构造缓存哈希时使用的输入，内容很多，适合继续定位
GODEBUG=gocachehash=1 go test ./...

gocachetest=1 适合先看“为什么命中或未命中”，gocachehash=1 适合确认某个文件或环境变量是否参与输入哈希。后者输出很长，建议只在需要追踪具体依赖时开启。

如果改变目标文件后输入哈希没有变化，重点检查文件位置和读取路径：它是否位于当前模块内，是否由测试进程直接打开，还是由外部工具、脚本或子进程间接读取。

稳定测试数据放进 testdata

固定样例最适合放在包目录下的 testdata。这个目录不会被当作普通包编译，却可以在测试运行时直接读取，也方便和测试代码一起做版本控制。

package config

import (
    "encoding/json"
    "os"
    "path/filepath"
    "testing"
)

type Config struct {
    Port int `json:"port"`
}

func TestLoadConfig(t *testing.T) {
    // 由测试进程直接打开模块内 fixture，便于缓存记录文件依赖
    path := filepath.Join("testdata", "config.json")
    data, err := os.ReadFile(path)
    if err != nil {
        t.Fatalf("读取 fixture 失败：%v", err)
    }

    // 验证输入内容，而不是只验证文件是否存在
    var cfg Config
    if err := json.Unmarshal(data, &cfg); err != nil {
        t.Fatalf("解析 fixture 失败：%v", err)
    }
    if cfg.Port != 8080 {
        t.Fatalf("端口不符合预期：%d", cfg.Port)
    }
}

修改 testdata/config.json 后，在包列表模式重新运行测试，模块内已打开文件的变化会参与后续缓存匹配。测试不需要为了“防缓存”额外写随机文件或更新时间戳。

模块外输入不能只传一个路径

集成测试经常从工作区外读取大数据文件、临时导出物或 CI 下载产物。仅把路径写进全局变量并不足以表达“这个文件的内容就是测试输入”。最简单可靠的策略，是这类测试直接使用 -count=1。

# 外部文件随时可能变化时，强制本次运行不复用测试结果
TEST_INPUT=/data/current.json go test -count=1 ./internal/importer

# 只清测试结果缓存，不删除构建缓存；适合一次性排障
go clean -testcache

go clean -testcache 能让下一次测试重新执行，但它不能修复依赖建模；后续仍可能再次缓存。go clean -cache 会连构建缓存一起清理，范围更大，通常没有必要。

如果外部输入很大、测试成本又高，希望继续利用缓存，可以由 CI 在运行前计算文件摘要，并把摘要作为环境变量传给测试。测试进程必须读取该变量，并核对摘要与实际文件一致。这样输入内容变化会带来环境变量变化，缓存键也随之变化。

package importer

import (
    "crypto/sha256"
    "encoding/hex"
    "os"
    "testing"
)

func TestExternalInput(t *testing.T) {
    // CI 负责根据当前文件内容生成这两个环境变量
    path := os.Getenv("TEST_INPUT")
    wantHash := os.Getenv("TEST_INPUT_SHA256")
    if path == "" || wantHash == "" {
        t.Fatal("缺少外部输入路径或内容摘要")
    }

    data, err := os.ReadFile(path)
    if err != nil {
        t.Fatalf("读取外部输入失败：%v", err)
    }

    // 核对摘要，避免调用方传入与文件内容不匹配的缓存标识
    sum := sha256.Sum256(data)
    gotHash := hex.EncodeToString(sum[:])
    if gotHash != wantHash {
        t.Fatalf("外部输入摘要不匹配：got %s", gotHash)
    }

    // 从这里开始执行真正的导入断言
}

摘要方案的前提是调用方每次都根据真实内容计算 TEST_INPUT_SHA256。如果无法保证这一点，就不要把它包装成可缓存测试，直接用 -count=1 更安全。

按输入来源选择处理方案

兼容现有 CI 时的改造顺序

现有流水线不必一次全部重写。可以先把最容易稳定化的输入迁入 testdata，再为仍需模块外文件的任务增加摘要契约，最后只给确实依赖动态系统的测试加 -count=1。这样既保证正确性，也不会让整个测试集失去缓存收益。

建议把测试拆成两层：单元测试只使用模块内 fixture 和测试替身，默认缓存；少量集成测试读取真实外部输入，使用独立命令并明确禁用结果缓存。比起全局执行 go clean -cache，这种分层更快，也更容易解释某次测试到底验证了什么。

常见问题

修改 Go 源文件为什么一定会重新测试？

源文件变化会改变测试二进制对应的构建身份，因此不会和旧测试身份匹配。输入文件问题主要发生在“测试代码没变，但运行时读取的数据变了”的场景。

只加 -v 能避开缓存吗？

不能。-v 属于可缓存测试参数，仍可能显示旧结果。明确要求重新执行时使用 -count=1。

每次都执行 go clean -cache 可以吗？

可以暂时绕开问题，但会丢掉构建缓存，拖慢所有包的编译，而且没有说明遗漏了哪项依赖。优先用 gocachetest 和 gocachehash 找到原因，只在需要时清理 -testcache。

参考资料

• Go 命令测试文档：https://pkg.go.dev/cmd/go#hdr-Test_packages
• Go 命令缓存帮助源码：https://go.dev/src/cmd/go/internal/help/helpdoc.go
• Go 测试缓存实现：https://go.dev/src/cmd/go/internal/test/test.go