因为embed.fs虽实现fs.fs接口，但未直接实现http.filesystem接口，必须用http.fs()包装；且其路径含嵌入目录前缀，需fs.sub剥离后才能正确映射路由。
为什么 embed.FS 不能直接传给 r.StaticFS？
因为 r.StaticFS 接收的是 http.FileSystem 接口，而 embed.FS 虽然实现了该接口，但它的根路径默认包含嵌入目录名。比如 //go:embed static/* 后，static/index.html 在 FS 中的路径是 static/index.html，不是 /index.html。直接传进去会导致访问 /assets/index.html 实际去查 static/assets/index.html，404。
必须用 fs.Sub 剥掉前缀：
//go:embed static/*
var staticFiles embed.FS
<p>subFS, _ := fs.Sub(staticFiles, "static") // 注意：这里 "static" 是 embed 指令里写的目录名
r.StaticFS("/assets", http.FS(subFS))
</p>
- 如果 embed 指令是
//go:embed public/**，那fs.Sub第二个参数就得是"public" -
fs.Sub返回的子文件系统不可写，且不支持Readdir（即禁用目录列表），这是安全优势 - 忽略错误会埋坑——
fs.Sub可能返回fs.ErrNotExist，尤其在测试环境路径拼错时
如何避免 Vue/React 刷新页面 404？
Gin 的 r.NoRoute 必须放在所有静态路由之后，否则它会提前拦截请求，导致 /assets/js/app.js 这类真实静态资源也被重定向到 index.html。
正确顺序：
- 先挂载静态资源：
r.StaticFS("/assets", ...) - 再注册 API 路由：
apiGroup := r.Group("/api"); apiGroup.GET(...) - 最后放
r.NoRoute，只兜底非 API、非静态资源的路径
典型错误写法是把 NoRoute 放最前面，结果所有请求都返回 index.html，JS/CSS 加载失败，控制台满屏 404。
补充：Vue Router 的 history 模式依赖后端兜底，但 Gin 不会自动识别 HTML 文件的 MIME 类型，建议显式设置：
r.NoRoute(func(c *gin.Context) {
c.Header("Content-Type", "text/html; charset=utf-8")
c.FileFromFS("static/dist/index.html", http.FS(subFS))
})
embed 打包后，怎么更新单个 HTML 或 JS 文件？
不能热更新——embed 是编译期行为，任何文件变更都必须重新 go build。这点和传统 Nginx + 静态目录部署有本质区别。
开发阶段可临时绕过：
- 用
build tags区分 dev/prod：dev 下跳过 embed，直接读磁盘文件；prod 下才启用 embed - 加一个开关变量，在 main 函数里判断：
if os.Getenv("ENV") == "dev" { r.Static("/assets", "./dist") } else { r.StaticFS(...) } - 注意：不要在 embed 和磁盘模式间混用同一路径前缀，否则路由冲突
真正上线前务必删掉开发分支逻辑，否则生产环境读不到嵌入资源。
哪些文件类型不适合用 embed？
大体积二进制文件（如 >10MB 的视频、PDF）会让二进制体积暴涨，启动变慢，且无法按需加载。
- 用户上传的文件、日志归档、报表导出 —— 这些应该存对象存储或本地磁盘，用
c.File或c.Stream动态响应 - 频繁变更的配置模板（如邮件 HTML 模板）—— embed 更新成本太高，更适合从 DB 或远程配置中心拉取
-
string类型嵌入仅限纯文本，图片/字体等二进制资源必须用[]byte或embed.FS，否则乱码
embed 的价值在于「部署确定性」，不是「万能打包器」。该放磁盘的就放磁盘，该走 CDN 的就走 CDN，嵌入只用于前端构建产物这类稳定、中等体积、与二进制强绑定的资源。
