Go embed.FS按版本目录组织静态资源的发布方式

我在把前端资源和 Go 服务打成一个二进制时，最先遇到的不是“怎么嵌入”，而是版本目录怎么留下来：如果每次升级都覆盖 static/app.js，旧页面引用的缓存文件就很难回滚。更稳的做法是让目录本身表达版本，例如 assets/v1/、assets/v2/，然后把 URL 前缀、文件系统裁剪和资源清单固定下来。

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

先把版本目录设计成发布边界

建议把入口 Go 文件和资源目录放在同一个包的可匹配范围内。目录可以这样组织：

assets/
  v1/
    index.html
    app.js
  v2/
    index.html
    app.js
server.go

在 server.go 中只声明一个文件系统变量。//go:embed 的模式相对声明变量的包目录解析，匹配不到文件会在构建阶段失败；目录模式还会递归收集子树，但默认排除点文件和下划线文件。

package main

import "embed"

// assets 保存所有随二进制发布的静态文件，版本目录不在运行时修改。
//go:embed assets
var assets embed.FS

这样做的关键不是把所有版本都暴露出去，而是把“发布包里有哪些版本”变成可检查的输入。embed.FS 是只读值，可以被多个 goroutine 安全使用；它不是可写缓存，也不会替你管理浏览器缓存。

用 fs.Sub 隔离版本路径并保持 URL 稳定

如果直接把整个 assets 交给文件服务器，内部目录会混进处理逻辑。更清楚的方式是先校验版本，再用 fs.Sub 裁剪目录：

package main

import (
    "embed"
    "fmt"
    "io/fs"
    "net/http"
)

// assets 与上面的 //go:embed assets 共用同一个只读资源树。
var assets embed.FS

func versionHandler(version string) (http.Handler, error) {
    // 白名单阻止请求把目录名变成任意文件系统路径。
    if version != "v1" && version != "v2" {
        return nil, fmt.Errorf("unsupported asset version %q", version)
    }
    // 裁剪后，FileServer 只看到当前版本目录内的文件。
    versionFS, err := fs.Sub(assets, "assets/"+version)
    if err != nil {
        return nil, err
    }
    // URL 前缀与内部目录解耦，后续可替换存储实现。
    return http.StripPrefix("/static/"+version+"/", http.FileServer(http.FS(versionFS))), nil
}

路由注册时把版本写死在配置或发布选择中，例如 /static/v2/，而不是从用户输入拼接任意路径。若想让每个版本都拥有相同的公开前缀，也可以在反向代理层把当前版本映射到 /static/，但回滚时要同步处理缓存。

清单生成要和资源选择使用同一棵树

目录存在不等于资源完整。发布阶段可以遍历裁剪后的文件系统，生成用于日志、健康检查或前端版本页的清单：

func listAssets(version string) ([]string, error) {
    versionFS, err := fs.Sub(assets, "assets/"+version)
    if err != nil {
        return nil, err
    }
    var files []string
    // WalkDir 使用 FS 内的斜杠路径，清单可直接用于资源请求核对。
    err = fs.WalkDir(versionFS, ".", func(path string, entry fs.DirEntry, walkErr error) error {
        if walkErr != nil {
            return walkErr
        }
        if entry.IsDir() {
            return nil
        }
        files = append(files, path)
        return nil
    })
    return files, err
}

这里的边界有两个：一是 fs.Sub 失败要直接阻止发布，二是清单里的路径必须使用 fs.FS 的斜杠规则，不要用操作系统路径函数改写。若资源需要哈希指纹，建议在构建阶段生成带哈希的文件名，再把映射表一并嵌入，而不是运行时重新计算。

发布和回滚时最容易忽略的边界

还要记住：嵌入文件会进入最终二进制，图片、字体和地图数据会明显增加体积；大文件不适合因为“部署方便”就全部内置。对于需要在线更新的内容，保留外部对象存储或文件系统，并让应用只保存版本清单。

常见问题

embed.FS 能在运行时写入资源吗？

不能。它提供的是只读文件系统，适合发布内置资源；需要写入时应使用外部存储。

为什么 fs.Sub 后还要做版本白名单？

fs.Sub 只负责裁剪已有目录，不负责业务授权。白名单能避免未知输入改变资源选择范围。

版本目录一定要叫 v1、v2 吗？

不一定，但命名必须稳定、可排序并与 URL 或清单约定一致；例如按构建号命名也可以。

实际落地时，我会把版本目录、资源清单和回滚开关放在同一个发布变更里：新版本先并存，清单确认完整后再切换默认入口，旧目录等缓存和回滚窗口结束再清理。