根本原因是路径映射未对齐：router.Static("/img", "./assets")请求/logo.png时查找./assets/logo.png，若实际在./assets/img/logo.png则404；常见于目录结构与URL前缀不一致、工作目录错误、大小写或权限问题。
router.Static 为什么访问图片返回 404
根本原因不是 Gin 不支持图片，而是路径映射没对上。Gin 的 router.Static 是前缀剥离 + 本地路径拼接，不自动递归查找或智能补全。比如你写 router.Static("/img", "./assets")，浏览器请求 /img/logo.png，Gin 就会去找 ./assets/logo.png —— 如果实际文件在 ./assets/img/logo.png，那就必然 404。
常见错误包括：
- 本地目录结构和 URL 前缀不一致（如 URL 用
/img，但文件实际在./public/images/） - 启动时工作目录不是项目根目录（
go run main.go在子目录下执行，./assets就指向错地方） - 忘记检查文件权限或大小写（Linux 下
Logo.png≠logo.png）
router.Static 和 router.StaticFS 该选哪个
router.Static 只接受字符串路径，内部调用 http.Dir，适合开发期快速验证；router.StaticFS 接收 http.FileSystem 接口，能对接 embed.FS、os.DirFS 或自定义实现，是生产环境唯一可靠选择。
关键区别：
- 用
embed.FS打包静态资源时，必须用router.StaticFS，否则运行时 panic：“invalid filesystem” -
router.Static("/static", "./dist")在 Docker 容器里大概率失效，因为工作目录不确定；router.StaticFS配合embed.FS或filepath.Abs路径才稳定 -
http.Dir默认允许目录列表（访问/static/且无index.html时会暴露文件名），router.StaticFS可配合自定义http.FileSystem关闭该行为
嵌入静态资源后 CSS/JS 图片全 404 怎么办
Go 的 embed 默认不递归、不包含隐藏文件、严格区分大小写，很容易漏掉资源。比如 //go:embed dist/* 只匹配 dist 下一级，不会进 dist/css 或 dist/img。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
正确做法：
- 用双星号递归：
//go:embed dist/** - 确认 embed 变量类型是
embed.FS，不是string或[]byte - 用
fs.WalkDir在启动时打印所有嵌入路径，验证dist/img/logo.png是否真在列表里 - 如果 embed 根目录含
dist这一层（即dist/logo.png被嵌入），而你想通过/img/logo.png访问，就得用fs.Sub(staticFiles, "dist")剥离前缀再传给http.FS
如何让前端路由刷新不 404（SPA 场景）
Gin 本身不内置“fallback to index.html”，但可以用通配符路由手动实现。这不是静态资源配置本身的问题，而是 SPA 的典型需求：所有未被其他路由匹配的请求，都应返回 index.html，由前端路由接管。
实操要点：
- 把
router.StaticFS("/assets", ...)放在所有其他路由之前（避免被通配符拦截） - 最后加一条通配符路由：
router.GET("/*path", func(c *gin.Context) { c.File("./dist/index.html") }) - 注意顺序：静态资源路由 → API 路由 → 通配符 fallback，否则图片、CSS 也会被 fallback 拦截
- 不要用
c.HTML，直接c.File更轻量，也避免模板引擎开销
最易被忽略的是 embed 路径与 URL 前缀的语义错位：你嵌入了 dist/**，但没用 fs.Sub 剥离 dist 层，导致 /img/logo.png 实际要从 dist/dist/img/logo.png 查找——这种问题在线下测不出，一到容器里就全挂。
