Static()参数顺序颠倒会导致全部404，因第一个参数必须是URL前缀、第二个是磁盘路径；NoRoute必须置于所有显式路由之后，否则API请求被拦截；生产环境应禁用目录列表，推荐用gin.Dir(dir, false)或http.FS(os.DirFS(dir))。
Static() 参数顺序写反会导致 404
最常见的错误是把 r.Static("/static", "./dist/static") 写成 r.Static("./dist/static", "/static")。Gin 不会报错，但所有静态请求全部 404——因为第一个参数是 URL 路径前缀，第二个才是磁盘路径，颠倒后 Gin 尝试把本地路径当 URL 前缀去匹配，自然找不到任何文件。
验证方式很简单：启动服务后访问 http://localhost:8080/static/js/app.js，如果返回 404，立刻检查这行代码；再用 fmt.Println(filepath.Abs("./dist/static")) 打印真实路径，确认它确实存在且可读。
- Windows 下路径分隔符不用手动替换，
filepath.Abs和http.Dir都能正确处理\和/ -
./dist/static是相对于main.go所在目录的路径，不是相对于当前工作目录（比如你从项目外执行go run ./cmd/server就容易出错） - 如果用 Docker，确保
./dist/static在镜像里真实存在，别只 COPY 了二进制文件
NoRoute 必须放在所有显式路由之后
SPA 应用需要根路径和任意前端路由都返回 index.html，靠 r.NoRoute() 实现。但它不是“兜底”那么简单——它会在所有 r.GET、r.POST 等注册的路由都匹配失败后才触发。如果把它写在 r.GET("/api/user") 前面，所有 API 请求都会被拦截并返回 HTML，导致接口调用全挂。
典型错误写法：
r.NoRoute(func(c *gin.Context) { c.File("./dist/index.html") })
r.GET("/api/user", handler)
正确顺序必须是：
r.GET("/api/user", handler)
r.GET("/api/order", handler)
// ... 其他所有 API 路由
r.NoRoute(func(c *gin.Context) { c.File("./dist/index.html") })
-
c.File("./dist/index.html")要求该文件物理存在，路径同样相对于main.go - 如果
index.html里引用了/static/js/app.js，那r.Static("/static", "./dist/static")必须已注册，否则 JS 加载失败 - 不建议用
r.GET("/", ...)替代NoRoute，前者只管/，后者覆盖所有未命中路径（如/about、/user/123）
StaticFS 比 Static 更安全，尤其生产环境
r.Static("/static", "./dist/static") 内部调用的是 http.Dir("./dist/static")，而默认的 http.Dir 允许目录遍历：访问 /static/..%2f..%2f/etc/passwd 可能泄露系统文件（取决于 Go 版本和 OS 权限），更常见的是访问 /static/（末尾斜杠）会列出整个目录内容——这对生产环境是严重风险。
改用 r.StaticFS("/static", http.Dir("./dist/static")) 并不能解决这个问题，真正有效的是禁用列表显示：
- 用
gin.Dir("./dist/static", false)（注意第二个参数为false），这是 Gin 自带的封装，等价于http.Dir但默认关闭目录列表 - 或直接用标准库：
http.FS(os.DirFS("./dist/static"))（Go 1.16+），它天然不支持目录列表 - 如果要用
embed.FS编译进二进制，必须用http.FS包装，不能直接传embed.FS
示例：
r.StaticFS("/static", gin.Dir("./dist/static", false))
嵌入静态资源时 embed.FS 的路径容易错一层
用 //go:embed static/* 声明变量后，static/ 是嵌入路径的一部分。如果你希望 /assets/style.css 对应嵌入的 static/style.css，就必须用 fs.Sub(staticFiles, "static") 去掉前缀，再传给 r.StaticFS("/assets", http.FS(subFS))。
常见错误是直接写 r.StaticFS("/assets", http.FS(staticFiles))，结果访问 /assets/style.css 会 404，因为实际路径是 /static/style.css。
-
fs.Sub第二个参数不能带尾部斜杠，写成"static/"会 panic -
embed.FS不支持写操作，所以上传类功能仍需独立存储路径 - 调试时可用
fs.WalkDir打印嵌入的所有文件名，确认结构是否符合预期
