embed一用就404的根本原因是路径层级不匹配：//go:embed static/dist/*将static/和dist/均嵌入fs，必须fs.sub(staticfiles, "static/dist")剥离前缀才能使readfile("main.js")生效；若漏掉static/层或直接传原fs，则文件查找失败导致404。
为什么 embed 一用就 404？路径嵌套没处理干净
直接 embed.FS 读整个 dist/ 目录，但访问 / 却返回 404，根本原因是 embed 的路径层级和 HTTP 路由不匹配。Go 的 //go:embed static/dist/* 会把 dist/ 这层目录也打进 FS 里，所以 fs.Sub(staticFiles, "static/dist") 才是正确起点，而不是 fs.Sub(staticFiles, "dist") 或直接传原 FS。
-
//go:embed static/dist/*→ FS 根目录包含static/→dist/→ 实际文件（三层） - 想让
/assets/main.js对应到dist/main.js，就得先fs.Sub(staticFiles, "static/dist") - 漏掉
static/这一层，ReadFile("main.js")就会报no such file or directory
StaticFS 挂载后，Vue Router 刷新 404 怎么破？
r.StaticFS("/assets", http.FS(subFS)) 只管 /assets/ 开头的请求，它不管 /dashboard 或 /user/profile 这类前端路由。这些路径没被任何 GET 路由注册，就会落到 NoRoute。但如果你在 NoRoute 里无条件返回 index.html，后端 API（比如 /api/user）也会被劫持——因为 Gin 的路由匹配是顺序优先，NoRoute 是兜底，不是“仅当非 API 路径时”。
- 必须区分静态资源路径（
/assets/、/favicon.ico）和 SPA 前端路由（/、/admin/*） - 推荐做法：用
r.GET("/*path", spaHandler)，且放在所有 API 路由之后、NoRoute之前 -
spaHandler中检查请求是否真该返回index.html：排除/api/、/healthz等已知 API 前缀 - 别依赖
NoRoute做 SPA fallback，它太粗暴
favicon.ico 和 index.html 都要单独处理？
是的。r.StaticFS("/assets", ...) 不会自动处理根路径下的 /favicon.ico 或 /robots.txt，除非你显式挂载或拦截。更麻烦的是，如果只用 StaticFS 挂载 dist/，而 dist/favicon.ico 在子目录里，Gin 默认不会从 / 自动映射过去——浏览器发的是 GET /favicon.ico，不是 GET /assets/favicon.ico。
- 方案一：用
r.StaticFile("/favicon.ico", "./dist/favicon.ico")（但要求文件在编译前存在，不适合 embed） - 方案二：用
http.FileServer包一层：faviconFS, _ := fs.Sub(embedFS, "static/dist")，再router.GET("/favicon.ico", func(c *gin.Context) { http.FileServer(http.FS(faviconFS)).ServeHTTP(c.Writer, c.Request) }) - 方案三：把
favicon.ico放进 embedFS 的顶层（同级于index.html），然后用fs.Sub(embedFS, "static/dist")后，它自然就在根下
embed 不能热更新，改了 HTML 怎么办？
embed 是编译期行为，源文件变更后必须重新 go build。这不是 bug，是设计使然。但开发阶段频繁 rebuild 很痛苦，容易误以为“代码没生效”，其实是二进制没重编译。
- 开发时建议用传统文件系统方式：
r.Static("./dist")，避开 embed - CI/CD 或发布包才启用 embed：加构建 tag，例如
//go:build embed，用go build -tags embed - 别在
main.go里混写 embed 和本地路径逻辑，容易漏掉条件编译 - 验证是否真打进去了：用
go tool objdump -s "main\..*" your_binary查看符号，或运行时fs.ReadDir打印文件列表
