根本原因是浏览器请求路径与磁盘文件路径未对齐：r.static("/static", "./dist")使/static/js/app.js映射到./dist/js/app.js，若文件实际在./dist/static/js/app.js则404；需确保url前缀、本地目录结构、html引用路径三者严格匹配，并将noroute置于所有路由之后。
为什么 r.Static("/static", "./dist") 还是 404？
根本不是 Gin 不工作，而是浏览器请求路径和磁盘文件路径没对齐。比如访问 /static/js/app.js，Gin 会去拼接 "./dist" + "/js/app.js"，也就是找 ./dist/js/app.js。如果真实文件在 ./dist/static/js/app.js，那就必然 404。
常见断点：
-
os.Getwd()返回的当前工作目录不等于main.go所在目录——启动前加fmt.Println(filepath.Abs("./dist"))看实际解析路径 - 误以为
r.Static("/assets", "./static")会自动映射到./static/assets/xxx，其实它只做“前缀剥离 + 路径拼接”，不会补子目录 - 前端构建时没设
publicPath: "/static/"，导致 HTML 里写的是src="js/app.js"（相对路径），浏览器发请求时变成/js/app.js，压根没走到/static路由
Static 和 StaticFS 到底该用哪个？
router.Static 是快捷封装，只接受字符串路径，内部调用 http.Dir；router.StaticFS 接收 http.FileSystem 接口，支持 embed.FS、os.DirFS 或自定义实现。
日常开发直接用 Static 就够了；但以下情况必须换 StaticFS：
- 想把静态资源编译进二进制（Go 1.16+
//go:embed dist/**）——Static会 panic：“invalid filesystem” - 需要从 S3、数据库或内存中读取文件，而非本地磁盘
- 想禁用目录列表（
http.Dir默认开启，访问/static/末尾带斜杠且无index.html时会暴露文件列表）
示例（嵌入式）：
//go:embed dist/**
var assetsFS embed.FS
<p>subFS, _ := fs.Sub(assetsFS, "dist")
r.StaticFS("/static", http.FS(subFS))
</p>
NoRoute 放错位置会导致 API 全挂
r.NoRoute 是兜底逻辑，不是“SPA fallback 中间件”。它必须放在所有其他路由注册之后，否则会提前吃掉 /api/user 这类真实接口请求。
正确顺序：
- 先注册所有
GET/POST等动态路由 - 再挂载
r.Static("/static", ...) - 最后放
r.NoRoute(...)，里面用c.File("./dist/index.html")返回首页
别在 NoRoute 里写 c.Redirect(302, "/index.html")——路由已结束，Redirect 只改响应头，不触发新匹配；也别忘了检查 index.html 是否存在，否则 c.File 会 panic。
Windows 下路径分隔符混用是隐形杀手
Gin 内部路径拼接依赖 filepath.Join，而 Windows 默认用反斜杠 。如果你手动拼路径如 "./dist\css\style.css" 或在构建脚本里硬编码 \，在 Linux 容器或 CI 环境中大概率失效。
安全做法：
- 一律用正斜杠
/写路径，Go 运行时会自动适配 - 避免手写路径拼接，优先用
filepath.Join("dist", "css", "style.css") - Docker 部署时，不要依赖当前工作目录，改用绝对路径：
abs, _ := filepath.Abs("./dist"); r.Static("/static", abs)
最易被忽略的一点：本地测试通过 ≠ 上线可用。务必在目标环境（如容器内、systemd service 启动）下跑一次二进制，用 curl -I http://localhost:8080/static/js/app.js 实测返回码和头信息。
