Static()参数顺序错误是404和panic主因：必须为r.Static("/static", "./dist/static")，颠倒则panic；NoRoute须置于所有路由之后以防API被拦截；embed.FS需用fs.Sub切子树且路径严格对应。
直接用 r.Static() 或 r.StaticFS() 就能部署，但 90% 的 404 和 panic 都来自路径顺序、embed 映射或 NoRoute 位置写错——不是 Gin 不行，是路径语义被误解了。
Static() 参数顺序写反导致 panic 或 404
r.Static() 固定要求「URL 前缀 → 本地磁盘路径」，颠倒必出问题：
-
r.Static("/static", "./dist/static")✅ 正确：浏览器访问/static/js/app.js会读取./dist/static/js/app.js -
r.Static("./dist/static", "/static")❌ 错误：Gin 把第一个参数当 URL 前缀，尝试去磁盘找目录./dist/static下的/static/js/app.js，直接 panic 或静默 404 - 验证方式：启动后手动请求
http://localhost:8080/static/js/app.js，再执行fmt.Println(filepath.Abs("./dist/static"))确认输出是否真指向文件所在位置 - Windows 用户手写路径别用
\，Go 的filepath.Join会自动处理，但硬写反斜杠可能被解析为转义字符
生产环境必须用 StaticFS + embed.FS，不能用 Static
r.Static() 内部调用 http.Dir，只支持真实磁盘路径；embed.FS 是内存文件系统，硬传会 panic：“invalid filesystem”：
- 正确写法：
//go:embed dist/**→ 定义var assets embed.FS→r.StaticFS("/assets", http.FS(assets)) - 注意嵌入路径和 URL 前缀的对应关系：如果
//go:embed dist/**，那dist/css/main.css对应浏览器请求/assets/css/main.css，不是/assets/dist/css/main.css - 单星号
dist/*不递归子目录，CSS/JS 404 很可能是因为漏了**；隐藏文件（如.gitignore）默认不被 embed，别依赖它们存在 - 上线前务必在目标环境跑二进制，用
fs.WalkDir(assets, ".", ...)打印所有嵌入路径，确认dist/index.html真在列表里
NoRoute 必须放在所有路由注册之后
SPA 应用靠 r.NoRoute() 返回 index.html 拦截前端路由，但放错位置会让 API 全挂：
- 错误顺序：
r.NoRoute(...)写在r.GET("/api/user")之前 → 所有/api/xxx请求都被兜底返回 HTML，前端 fetch 拿到的是 200 HTML 文本，不是 JSON - 正确顺序：先注册全部
r.GET("/api/...")，再注册页面级路由（如r.GET("/", ...)），最后才r.NoRoute() -
NoRoute里别调c.Redirect()或改c.Request.URL.Path，路由匹配已结束，这些操作无效 - 务必检查
./dist/index.html（或 embed 中的对应路径）真实存在且可读，否则c.File()或c.FileFromFS()会 panic
最常被忽略的点：Gin 不自动识别项目根目录，它只认当前工作目录。Docker 或 systemd 启动时，./dist 很可能根本不存在——要么用 filepath.Abs("dist") 转绝对路径，要么老老实实用 embed.FS 把资源编译进二进制，一劳永逸。
