嵌入资源更新后程序仍读到旧内容，构建缓存应如何排查

使用 //go:embed 后，资源更新却仍读到旧内容，先不要把问题简单归咎于 Go 的构建缓存。常见根因是资源没有命中匹配模式、程序仍在运行旧进程，或者容器构建上下文没有带上新文件。Go 的构建缓存会根据 Go 源文件、编译器和编译参数判断是否复用；真正需要清理缓存的场景并不多。

官方地址：https://pkg.go.dev/embed

先确认资源真的进入了 embed 变量

//go:embed 的模式相对于声明变量的 Go 源文件所在包解析。变量只能是 string、[]byte 或 embed.FS；目录模式会递归匹配子目录，但默认排除名称以点号或下划线开头的文件。资源改了却没有变化时，第一步是核对路径、文件名和模式，而不是清空缓存。

package webassets

import (
    "embed"
    "fmt"
)

//go:embed assets/config.json
var files embed.FS

func ReadConfig() ([]byte, error) {
    // 路径相对于当前包目录，使用正斜杠。
    data, err := files.ReadFile("assets/config.json")
    if err != nil {
        // 返回错误，避免静默使用旧默认值。
        return nil, fmt.Errorf("读取嵌入配置: %w", err)
    }
    return data, nil
}

如果模式写成 assets/*.json，新文件必须满足通配规则；如果使用字符串或字节切片，模式只能匹配一个文件。还要留意指令必须紧邻变量声明。可以用 go list -json 查看 Go 工具链识别到的 EmbedPatterns：

# 在包含 go.mod 的项目根目录查看 embed 模式。
go list -json ./path/to/webassets | grep -A3 'EmbedPatterns'

把构建缓存、旧进程和模块缓存分开排查

Go 有构建缓存和模块缓存两个概念。构建缓存保存编译产物，位置可由 GOCACHE 指定；模块缓存保存下载的依赖源码，通常由 GOMODCACHE 指定。更新项目内嵌资源时，先确认运行的是否还是旧进程或旧二进制：

# 显示当前构建缓存位置，避免清理了错误目录。
go env GOCACHE

# 强制当前构建链路重新编译依赖包，不改变模块下载内容。
go build -a -o ./bin/server ./cmd/server

# 仅在确认构建缓存异常时清理全部构建产物。
go clean -cache

go build -a 是一次性排查手段，不应成为日常构建参数。若资源来自依赖模块或 vendor 目录，检查依赖实际加载位置和 vendor/modules.txt；这属于模块来源问题，清理 build cache 并不会替换模块内容。

给嵌入内容加可识别的版本标记

“读到旧内容”必须有可观察证据。可以在资源中放一个短版本字段，或在启动日志中输出内容哈希。下面的示例只演示判断逻辑，输出值应来自当前构建实际嵌入的内容：

package main

import (
    _ "embed"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
)

//go:embed assets/config.json
var config []byte

func main() {
    // 哈希用于确认二进制携带的资源版本，不替代配置校验。
    sum := sha256.Sum256(config)
    fmt.Println("embedded-config-sha256=" + hex.EncodeToString(sum[:8]))
}

若哈希已经变化但服务仍返回旧文本，问题就不在 embed 或构建缓存，而在服务进程、内存缓存、反向代理或客户端缓存。这个分界能避免反复执行清理命令。

容器构建时重点看 build context 和启动文件

本地构建正确、容器仍旧时，常见原因是执行 docker build 时的上下文目录不包含新资源，或者多阶段构建复制了旧阶段产物。检查 Dockerfile 的 COPY 范围、.dockerignore 是否排除了资源目录，以及最终 ENTRYPOINT 指向的二进制。不要只给构建命令加 --no-cache：它能绕过 Docker 层缓存，却不能修复缺失的 build context，也不能让正在运行的旧容器自动换成新文件。

常见问题

修改 embed 文件后一定要执行 go clean -cache 吗？

不一定。正常情况下 Go 会把相关输入纳入构建判断；先重新构建、确认输出二进制路径并重启进程。只有发现缓存异常或外部输入没有被正确纳入时，才用 go clean -cache 做一次对照。

为什么 go build 成功，运行结果却没有更新？

最常见是运行脚本仍指向旧二进制，或服务进程没有重启。给嵌入内容加短哈希并在启动时打印，可以快速确认实际运行的文件。

go clean -modcache 能解决嵌入资源旧内容吗？

通常不能。go clean -modcache处理的是下载的模块源码；项目自身的 embed 资源与构建缓存是另一条链路，先不要混用两个清理命令。