Gin 中静态文件 URL 加 ?v=xxx 必然 404，因 Static() 底层 http.FileServer 仅按完整路径字符串匹配，不解析 query；正确做法是将哈希嵌入文件名（如 app.3f8a2d.js），HTML、磁盘文件、路由三者严格一致，并配 Cache-Control 头。
直接给静态文件 URL 加 ?v=1.2.3 参数在 Gin 中无效——Static() 完全忽略 query string，路径不匹配就 404。
为什么 ?v=xxx 在 Gin 里必然 404
Gin 的 Static() 底层用的是 http.FileServer，只做纯路径字符串匹配。请求 /static/js/app.js?v=1.2.3 时，它查找的磁盘路径是 ./dist/static/js/app.js?v=1.2.3（带问号），而实际文件是 ./dist/static/js/app.js。两者字面不等价，直接返回 404。
这不是配置问题，是设计使然：query 不参与文件系统映射。
- 前端模板里写
<script src="/static/js/app.js?v={{ .Version }}">→ 必然 404 - Webpack/Vite 构建后没重命名文件，只改 HTML 里的
src→ 依然 404 - 用中间件 strip query 再转发 → 可行但绕过 CDN 缓存逻辑，且浏览器对
?t=的缓存行为不一致
正确做法：把哈希 baked 进文件名，三者严格一致
核心不是“怎么加参数”，而是“让 URL 路径本身携带版本信息”，并确保 HTML、磁盘、路由三者完全对齐。
- 前端构建必须生成带内容哈希的文件名，例如
app.3f8a2d.js、style.b1c2e4.css - HTML 模板中引用的路径要和输出文件名完全一致：
<script src="/static/js/app.3f8a2d.js"> - Gin 静态服务保持默认配置：
r.Static("/static", "./dist/static")，不做任何 query 处理 - 检查
./dist/static/js/app.3f8a2d.js确实存在，大小写、点、横线一个都不能错 - Windows 下用
filepath.ToSlash()统一路径分隔符，避免\导致os.Stat失败
模板里怎么安全注入哈希文件名
不能手写或硬编码哈希值。得靠构建工具生成 manifest 或通过 Go 模板变量传入。
- Webpack +
HtmlWebpackPlugin：启用filename: '[name].[contenthash:8].js'，再用webpack-manifest-plugin输出manifest.json，Go 后端读取后注入到模板数据 - Vite：配置
build.rollupOptions.output.assetFileNames: 'assets/[name].[hash].js'，同样导出映射表供 Go 加载 - 简单项目可直接用构建脚本生成
version_map.go，定义var JSMap = map[string]string{"app": "app.a1b2c3.js"}，模板里调{{ index .JSMap "app" }} - 绝对不要在模板里拼接
"app." + .Hash + ".js"—— 哈希来源不可靠，容易脱节
额外但关键：Cache-Control 必须手动加
Static() 默认不设缓存头。即使文件名带哈希，浏览器仍可能发条件请求（If-None-Match）或反复校验。
- 用中间件统一加头：
c.Header("Cache-Control", "public, max-age=31536000")，仅对/static/路径生效 - 别试图在
StaticFS或自定义http.FileSystem里塞 header —— Gin 没暴露接口，改源码不现实 - CDN 层（如 Cloudflare）也要配好缓存规则，否则边缘节点可能忽略 max-age
最易被忽略的一点：哈希文件名只是防缓存的第一步；没有正确的 Cache-Control，浏览器仍可能发起不必要的 HEAD 请求或重复下载——尤其在弱网下影响首屏速度。
