因为Gin的Static()只按路径匹配文件，不解析query string，/static/js/app.js?v=1.2.3与磁盘文件./dist/static/js/app.js路径不等价，导致404；必须将版本哈希 baked 进文件名并确保HTML引用、URL路径、磁盘路径三者完全一致。
为什么加版本号后 still 404？
加了 v=1.2.3 或 ?t=1678901234 后资源仍 404，本质是 Gin 的 Static() 不解析 query string —— 它只按路径匹配文件，/static/js/app.js?v=1.2.3 和磁盘上 ./dist/static/js/app.js 完全不等价，直接被忽略。
常见错误写法：r.Static("/static", "./dist/static") + 前端 HTML 里写 <script src="/static/js/app.js?v=1.2.3"></script> → 请求路径带 query，Gin 按字面匹配失败。
- 必须确保前端构建时把版本号 baked 进文件名（如
app.a1b2c3.js），而不是靠 URL 参数 - HTML 中引用路径也要同步更新，比如用 Webpack 的
HtmlWebpackPlugin或 Vite 的build.rollupOptions.output.assetFileNames控制输出名 - 若硬要用 query 控制缓存，得自己写中间件 strip query 再转发给 StaticHandler，但不推荐——CDN 和浏览器对 query 缓存行为不一致
如何让 Gin 正确服务带哈希的文件名？
前端打包生成带内容哈希的文件（如 app.3f8a2d.js）后，Gin 必须原样映射路径。关键不是改 Gin，而是保证磁盘路径、URL 路径、HTML 引用三者完全一致。
示例结构：
./dist/
├── index.html
└── static/
└── js/
└── app.3f8a2d.js
对应配置：
r.Static("/static", "./dist/static") → 访问 /static/js/app.3f8a2d.js 才能命中
- 检查
index.html里<script src="/static/js/app.3f8a2d.js">是否真实存在且拼写无误（大小写、点、横线） - 确认工作目录是
main.go所在位置，用filepath.Abs("./dist/static")打印路径验证 - Windows 下注意路径分隔符：统一用
filepath.ToSlash()转成/，避免\导致os.Stat失败
生产环境 Cache-Control 怎么设才有效？
Gin 默认不设缓存头，浏览器可能反复请求相同文件。但直接在 Static() 上加 Cache-Control 不行 —— 它没暴露 header 设置接口。
正确做法是拦截静态路径，手动加头：
r.Use(func(c *gin.Context) { if strings.HasPrefix(c.Request.URL.Path, "/static/") { c.Header("Cache-Control", "public, max-age=31536000") } c.Next() })
- 只对
/static/开头的请求生效，不影响 API 路由 -
max-age=31536000（1年）适合带哈希的文件；未哈希的文件（如favicon.ico）建议用短周期，如max-age=86400 - 别漏掉
c.Next()，否则后续 handler 不执行 - 如果用了
StaticFS或 embed，同样适用该 middleware —— 只要路径匹配规则一致
嵌入式部署（embed.FS）下怎么处理版本？
用 Go 1.16+ embed 把静态资源编译进二进制时，版本控制逻辑不变，但路径构造方式微调。
关键点：
//go:embed dist/static/*var staticFiles embed.FSsubFS, _ := fs.Sub(staticFiles, "dist/static")r.StaticFS("/static", http.FS(subFS))
- embed 的路径前缀必须和实际目录结构严格一致，
dist/static/少一层或多一层都会导致 404 - 构建时每次变更文件内容，embed 自动生成新哈希，二进制本身即“版本标识”，无需额外加 query
- 嵌入后无法 runtime 修改文件，所以所有版本决策必须在 build 阶段完成
真正容易被忽略的是：嵌入资源的路径前缀与 HTML 中引用路径的对应关系，一旦错位，连 index.html 都加载不了，整个 SPA 直接白屏。
