Static()路径参数顺序错误是最常见404原因：必须为r.Static("/static", "./dist/static")，颠倒则panic或失效；NoRoute须置于所有路由之后以确保API不被拦截，且需验证index.html存在、路径正确、Gin版本≥v1.9.1以支持ETag缓存。
Static() 路径参数写反导致 404
最常见错误是把 URL 前缀和磁盘路径顺序搞混：r.Static("/static", "./dist/static") 是对的，r.Static("./dist/static", "/static") 会直接 panic 或静默失效。Gin 按照「路由前缀 → 本地路径」固定顺序解析，颠倒后它会尝试把 /static 当作目录去读取，而该路径下显然没有 index.html 等文件。
验证方式很简单：启动服务后手动访问 http://localhost:8080/static/js/app.js，如果返回 404，立刻执行 fmt.Println(filepath.Abs("./dist/static")) 看输出是否指向真实文件位置。Windows 用户尤其注意斜杠方向——Go 自动处理 filepath.Join，但手写路径时别用反斜杠 \。
NoRoute 必须放在所有显式路由之后
SPA 应用（Vue/React）需要前端路由接管 /about、/user/123 这类路径，靠 r.NoRoute() 返回 index.html 实现。但如果你把 NoRoute 写在 r.GET("/api/user") 之前，所有 API 请求都会被兜底捕获，返回 HTML 而不是 JSON，前端 fetch 拿到的是 200 HTML 文本，而不是预期的 200 JSON。
- 正确顺序：注册全部
r.GET("/api/...")→ 注册页面级路由（如r.GET("/", ...)）→ 最后加r.NoRoute(...) -
NoRoute里不要用c.Redirect或改c.Request.URL.Path，路由已结束，这些操作无效 - 务必检查
./dist/index.html是否真实存在且可读，否则c.File()会 panic
embed.FS 编译进二进制时路径易错
用 Go 1.16+ 的 embed 打包静态资源，能避免部署时漏文件或路径错乱，但嵌入路径和 StaticFS 的映射关系容易出错。
比如你写了 //go:embed static/*，那 static/ 是 embed.FS 的根；但调用 r.StaticFS("/assets", http.FS(subFS)) 时，浏览器请求 /assets/css/main.css 实际对应的是 embed.FS 里的 static/css/main.css —— 中间不能多一层 static。
关键点：
- 用
fs.Sub(staticFiles, "static")去掉前缀，确保 FS 根就是你要暴露的资源目录 - 别直接传
http.Dir("./dist")给StaticFS，那是运行时路径，和 embed 冲突 - 编译后用
strings.Contains(r.Dump(), "static/css")类似方式简单验证资源是否真被嵌入
生产环境必须确认 Gin 版本 ≥ v1.9.1
旧版 Gin（v1.9.0 及之前）的 StaticFS 不生成 ETag 响应头，浏览器每次都要重拉 JS/CSS，无法利用 304 缓存。这个问题在开发时不易察觉，上线后流量陡增才暴露。
检查方式：curl -I http://localhost:8080/static/js/app.js，看响应头是否有 ETag。没有？升级 Gin。
另外，http.Dir 默认允许目录列表（访问 /static/ 显示文件名），生产环境必须禁用——Gin 的 StaticFS 不提供开关，只能自己包装 http.FileSystem 或换用 embed.FS 规避。
