直接用engine.Static("/", "./dist")会404，是因为Vue Router的history模式下，Gin仅按真实文件路径查找，/user/profile等前端路由在dist目录中不存在物理文件，故返回404；必须通过NoRoute兜底返回index.html，由前端路由接管。
为什么直接用 engine.Static("/", "./dist") 会 404？
因为 Vue Router 默认用 history 模式，index.html 只在根路径（/）被正确返回；而访问 /user/profile 这类前端路由时，Gin 并不知道该返回 index.html，它只按真实文件路径查找 —— ./dist/user/profile 显然不存在，于是返回 404。
这不是 Gin 的 bug，是前后端路由职责错位：Vue 负责客户端路由跳转，但首次加载或刷新时，服务端必须兜底返回 index.html，让前端 JS 接管后续路由逻辑。
- 检查你的
router/index.js或router/index.ts：如果看到createWebHistory()或mode: 'history'，就确认是 history 模式 -
engine.Static()只服务静态文件，不处理路由 fallback - 别指望改
publicPath或base能绕过这个问题 —— 它们影响资源路径解析，不解决服务端 404
用 http.FileServer + http.StripPrefix 手动 fallback
这是最轻量、兼容性最强的方案，不依赖 Go 版本，也不需要 embed。核心思路是：先尝试按路径找真实文件；找不到时，强制返回 ./dist/index.html。
示例代码片段（Gin v1.9+）：
立即学习“前端免费学习笔记（深入）”；
vue-composition-api-best-practices
下载
Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。
fs := http.FileServer(http.Dir("./dist"))
r.NoRoute(func(c *gin.Context) {
if _, err := os.Stat("./dist" + c.Request.URL.Path); os.IsNotExist(err) {
c.Header("Content-Type", "text/html; charset=utf-8")
c.Status(200)
c.File("./dist/index.html")
return
}
fs.ServeHTTP(c.Writer, c.Request)
})
- 必须放在
r.NoRoute()里，不能用r.Static()替代 - 注意路径拼接：
"./dist" + c.Request.URL.Path，不是c.Request.URL.Path直接传给os.Stat - 如果
dist在子目录（如./frontend/dist），所有路径都要同步调整 - 此方式对
favicon.ico、manifest.json等根级静态资源也有效，无需额外配置
Go 1.16+ 用 embed.FS 打包进二进制，避免部署时传 dist 目录
当你希望最终只有一个可执行文件（比如发给客户或跑在无文件系统的容器里），embed.FS 是官方推荐路径。但要注意：它不能直接和 gin.Engine.StaticFS 配合使用，因为后者不支持自定义 Open 行为 —— 必须重写 http.FileSystem 接口。
关键步骤：
//go:embed dist/*
var dist embed.FS
<p>func main() {
r := gin.Default()
fs := &assetFS{fs: dist, prefix: "dist"}
r.NoRoute(func(c *gin.Context) {
c.Header("Content-Type", "text/html; charset=utf-8")
c.Status(200)
c.FileFromFS("/", fs)
})
r.Run(":8080")
}</p><p>type assetFS struct {
fs embed.FS
prefix string
}</p><p>func (a *assetFS) Open(name string) (http.File, error) {
f, err := a.fs.Open(path.Join(a.prefix, name))
if err != nil && name != "/" {
return a.fs.Open(path.Join(a.prefix, "index.html"))
}
return f, err
}
-
go:embed dist/*必须写在main包，且变量声明前不能有空行 -
assetFS.Open是 fallback 的核心：当请求路径找不到时，主动回退到index.html - 不要用
gin.StaticFS("/", fs)—— 它不会触发 fallback，遇到非存在路径仍 404 - 打包命令仍是
go build -o app ./cmd，无需额外工具链
Vue 打包前必须确认的三项配置
即使后端托管逻辑完全正确，前端配置出错也会导致白屏、资源 404 或路由失效。这三个点最容易被忽略：
-
vue.config.js中publicPath必须设为"./"（相对路径）或""（空字符串），不能是"/"或"https://cdn.com/"；否则生成的index.html里 JS/CSS 路径会指向根或外域 -
router的base选项要和实际部署路径一致：如果 Gin 用r.Static("/assets", "./dist/assets")暴露资源，那base应设为"/"；如果整个 Vue 应用挂载在/admin下，则base: "/admin/"，且 Gin 的NoRoute也要适配路径前缀 - 构建后手动打开
dist/index.html浏览器本地双击运行 —— 会因 CORS 白屏，这不是问题，仅说明你必须通过 HTTP 服务访问（如 Gin 启动后访问localhost:8080）
真正麻烦的从来不是代码怎么写，而是 publicPath、base、Gin 路由前缀、Nginx location 四者之间的路径对齐 —— 少一个斜杠或错一层嵌套，资源就加载失败，且浏览器控制台报错往往不直接提示根源。
