根本原因是Gin路径映射严格字面匹配，不自动补斜杠、不fallback到index.html、也不标准化路径；常见错误包括目录不存在、工作路径错误、Windows路径分隔符混用、Static路径尾部多斜杠、HTML引用前缀与挂载前缀不一致。
为什么 r.Static("/static", "./dist/static") 映射后仍 404？
根本原因是 Gin 的路径映射是严格字面匹配，不自动补斜杠、不 fallback 到 index.html、也不做路径标准化。常见错误包括：
-
./dist/static目录实际不存在，或工作目录不是main.go所在位置 —— 启动前加一句fmt.Println(filepath.Abs("./dist/static"))确认真实路径 - Windows 下混用
\和/，导致os.Stat失败 —— 统一用filepath.ToSlash()转换后再传入 - 写成
r.Static("/static/", "./dist/static")（带尾部斜杠）—— URL 匹配会失败，必须是/static，不是/static/ - 前端 HTML 中引用的是
/assets/js/app.js，但你挂载的是/static—— 虚拟路径前缀必须和 HTML 中的<script src="...">完全一致
如何让 / 和子路径都返回 index.html（SPA 场景）？
Gin 默认不支持 SPA 的 history 模式 fallback，r.Static() 只响应明确文件路径，不处理目录或缺失路由。
- 必须把
r.NoRoute()放在所有 API 路由注册之后，否则会拦截/api/xxx等合法接口 - 直接用
c.File("./dist/index.html")最简可靠；不要用c.Redirect()，它暴露真实路径且多一次 HTTP 跳转 - 如果
index.html里引用了/static/main.js，那r.Static("/static", "./dist/static")就必须存在且可访问，否则页面白屏 - 注意：Gin 的
c.File()自动防御目录遍历（如../../etc/passwd），比手拼路径安全
r.StaticFS 和 r.Static 有什么关键区别？
r.StaticFS 接收一个 http.FileSystem，比 r.Static 更底层、更灵活，但也更容易出错。
-
r.Static("/static", dir)是语法糖，内部等价于r.StaticFS("/static", http.Dir(dir)) - 若你用
embed.FS或自定义压缩文件系统（如zip.Reader），必须用StaticFS；Static只支持本地磁盘目录 -
http.Dir("./dist")在 Windows 下可能因大小写或分隔符敏感导致 404，建议先filepath.Abs再filepath.ToSlash -
StaticFS不会自动列出目录内容 —— 那是http.FileServer的行为，Gin 默认禁用，避免信息泄露
生产环境部署时最容易忽略的三件事
开发能跑 ≠ 上线可用。这几个点不处理，上线后资源加载慢、MIME 错误、缓存混乱很常见。
立即学习“go语言免费学习笔记（深入）”；
- 静态资源响应头没设
Cache-Control—— 前端 JS/CSS 更新后用户仍用旧版，加中间件手动设置：c.Header("Cache-Control", "public, max-age=31536000") - MIME 类型未覆盖全 —— 比如
.webp、.woff2可能被当成text/plain，浏览器拒载；建议用gin-contrib/secure或自定义 MIME map - CDN 路径没替换 —— 开发用
/static/，上线要替换成https://cdn.example.com/static/，别硬编码在 HTML 里，构建阶段用sed或模板变量注入
路径映射本身不复杂，真正卡住人的永远是工作目录、斜杠方向、URL 前缀与 HTML 引用是否完全对齐 —— 这三者差一个字符，就 404。
