直接用 r.StaticFS("/", http.FS(fs)) 会拦截所有请求导致后端接口404，因其注册 /*filepath 通配路由且优先级最高；正确做法是限定静态路由前缀、用 fs.Sub 剥离 dist 前缀，并在 NoRoute 中返回 index.html。
为什么直接用 r.StaticFS("/", http.FS(fs)) 会炸掉后端接口
因为 r.StaticFS 在 Gin 里本质是注册了一个 /*filepath 的通配路由，优先级高于所有其他 GET/POST 路由。一旦你把它挂到 /，所有请求——包括 /api/user、/healthz——都会先被它拦截，然后去嵌入文件系统里找对应路径。找不到就 404，根本没机会走到你的业务 handler。
这不是 bug，是设计使然：Gin 的静态路由匹配逻辑就是“先到先得”，没有自动排除 API 前缀的智能判断。
- 现象：后端接口全部返回 404，但
/index.html能打开 - 原因：Gin 把
/api/xxx当作静态路径去 embed.FS 里查，自然查不到 - 关键点：
r.StaticFS不区分“前端路由”和“API 路由”，它只认路径字面量
fs.Sub 前缀处理不干净，导致 CSS/JS 加载 404
Vue 打包后生成的 dist/ 目录结构通常是 dist/index.html、dist/js/app.xxx.js、dist/css/style.xxx.css。如果你用 //go:embed dist/*，embed.FS 的根目录就是 dist/ 本身；但若误写成 //go:embed dist（少个 /*），整个 dist 文件夹会被当做一个文件，读取失败。
更常见的是 fs.Sub 层级搞错：比如 fs.Sub(embedFS, "dist") 后再挂到 /，浏览器请求 /js/app.js 实际会去查 embedFS 下的 js/app.js —— 但真实路径其实是 dist/js/app.js，所以必须确保 fs.Sub 剥掉的是完整前缀。
- 正确做法：
//go:embed dist/*→fs.Sub(f, "dist")→r.StaticFS("/", http.FS(subFS)) - 错误写法：
//go:embed dist或fs.Sub(f, "dist/")（末尾斜杠会导致路径错位） - 验证技巧：启动后 curl -I http://localhost:8080/js/，看响应头是否含
Content-Type: application/javascript
SPA 场景下必须用自定义 NoRoute 中间件，不能只靠 StaticFS
Vue Router 默认用 history 模式，访问 /dashboard/user 时浏览器发请求给后端，但这个路径在 embed.FS 里并不存在。标准解法是：所有未被 API 或静态资源匹配的请求，都返回 index.html，让前端 router 自行解析路径。
但注意，这个逻辑不能塞进 r.NoRoute 然后直接 c.File() —— 因为 c.File() 依赖磁盘路径，而 embed.FS 是内存只读文件系统，必须用 c.Data() 手动读取。
- 步骤：先尝试从 embed.FS 读
index.html，成功则返回；失败才 404 - 代码核心：
content, _ := fs.ReadFile(staticFS, "index.html")→c.Data(200, "text/html; charset=utf-8", content) - 顺序关键：NoRoute 必须放在所有
r.GET、r.POST和r.StaticFS之后，否则不会触发 - 别漏掉：静态资源（如
/favicon.ico）要单独处理，否则也会被 NoRoute 拦截
生产环境必须禁用目录遍历，且注意 embed.FS 的只读特性
http.FS 包装后的 embed.FS 天然禁止目录遍历（比如访问 /.. 或 /dist/../../../etc/passwd），这点比 http.Dir 安全得多。但容易忽略的是：embed.FS 在编译时固化，运行时无法更新文件内容——改了 Vue 源码必须重新 go build。
- 安全确认：无需额外配置，embed.FS 默认拒绝任何越界路径访问
- 更新成本：每次前端变更都要重编译后端二进制，CI/CD 流程需同步调整
- 调试建议：本地开发时可暂时用
r.Static("/static", "./dist")，上线再切回 embed，避免反复编译 - 体积影响：Vue 打包后 assets 总大小直接影响二进制体积，建议开启 gzip 压缩传输（Gin 默认支持）
