# Go embed 排除下划线开头文件导致前端动态路由模块加载失败
## 问题现象
在生产环境部署后，访问前端动态路由页面（如 `/admin/packages/123` 编辑页面）时出现以下错误：
“`
TypeError: Failed to fetch dynamically imported module:
http://example.com/assets/_id_-B9QlF12P.js
“`
浏览器请求该 JS 文件返回 404，但服务器上的构建产物中确实存在该文件。
## 问题分析
### 1. 初步排查
首先怀疑是 CDN 缓存问题，但绕过 CDN 直接访问服务器 IP 仍然报错，排除缓存因素。
### 2. 检查 Docker 构建流程
项目的 Dockerfile 使用多阶段构建，前端构建产物被嵌入到 Go 二进制中：
“`dockerfile
# 阶段1: 构建前端
FROM node:22-alpine AS frontend-builder
WORKDIR /app/frontend
COPY frontend-new/package.json frontend-new/pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install –frozen-lockfile
COPY frontend-new/ .
RUN pnpm build
# 阶段2: 构建后端
FROM golang:1.21-alpine AS backend-builder
WORKDIR /app
COPY backend/ .
COPY –from=frontend-builder /app/frontend/dist ./cmd/embedded/dist
RUN go build -o main ./cmd/main.go
“`
CI 构建成功，镜像也更新了，但问题依然存在。
### 3. 检查静态文件服务代码
Go 后端使用 `embed.FS` 嵌入前端文件：
“`go
//go:embed embedded/dist
var embeddedFiles embed.FS
func setupEmbeddedFrontend(r *gin.Engine) {
distFS, _ := fs.Sub(embeddedFiles, “embedded/dist”)
r.GET(“/assets/*filepath”, func(c *gin.Context) {
filepath := strings.TrimPrefix(c.Request.URL.Path, “/”)
c.FileFromFS(filepath, http.FS(distFS))
})
}
“`
代码逻辑正确，路径处理也没有问题。
### 4. 定位真正原因
编写测试代码验证 embed 是否正确加载文件：
“`go
//go:embed embedded/dist
var embeddedFiles embed.FS
func main() {
distFS, _ := fs.Sub(embeddedFiles, “embedded/dist”)
// 检查文件是否存在
testFiles := []string{
“assets/index-YeatH9nV.js”, // 正常文件
“assets/_id_-B_t0u3n5.js”, // 下划线开头文件
}
for _, f := range testFiles {
_, err := fs.Stat(distFS, f)
fmt.Printf(“%s: %v\n”, f, err == nil)
}
}
“`
结果：
“`
assets/index-YeatH9nV.js: true
assets/_id_-B_t0u3n5.js: false ← 问题！
“`
**结论：Go embed 排除了以 `_` 开头的文件！**
## 根本原因
Go 的 `//go:embed` 指令遵循 Go 工具的默认行为：**排除以 `_` 或 `.` 开头的文件和目录**。
这是 Go 模块系统的设计决定，类似于：
– `_test.go` 文件被排除在正常编译之外
– `.git`、`.github` 等隐藏目录被忽略
而 Vite 构建动态路由时，生成的 chunk 文件名格式为 `_id_-xxxx.js`（`_id_` 来自路由参数 `[id].vue），恰好以下划线开头，导致这些文件被 Go embed 静默排除。
## 解决方案
使用 `all:` 前缀告诉 embed 包含所有文件：
“`go
//go:embed all:embedded/dist
var embeddedFiles embed.FS
“`
`all:` 前缀会包含所有文件，包括以 `_` 或 `.` 开头的文件。
### 验证修复
“`go
//go:embed all:embedded/dist
var embeddedFiles embed.FS
func main() {
distFS, _ := fs.Sub(embeddedFiles, “embedded/dist”)
testFiles := []string{
“assets/_id_-B_t0u3n5.js”,
“assets/index-YeatH9nV.js”,
}
for _, f := range testFiles {
stat, err := fs.Stat(distFS, f)
if err != nil {
fmt.Printf(“%s: NOT FOUND\n”, f)
} else {
fmt.Printf(“%s: EXISTS (%d bytes)\n”, f, stat.Size())
}
}
}
“`
结果：
“`
assets/_id_-B_t0u3n5.js: EXISTS (23621 bytes) ✓
assets/index-YeatH9nV.js: EXISTS (526425 bytes) ✓
“`
## 最佳实践
1. **使用 `all:` 前缀**：当嵌入目录可能包含特殊命名的文件时，使用 `all:` 前缀
“`go
//go:embed all:static
var staticFiles embed.FS
“`
2. **添加构建验证**：在 CI/CD 中添加验证步骤，确保关键文件被正确嵌入
“`go
// 构建后验证
func verifyEmbeddedFiles() error {
required := []string{“assets/_id_”}
for _, prefix := range required {
matches, _ := fs.Glob(distFS, prefix+”*”)
if len(matches) == 0 {
return fmt.Errorf(“no files matching %s found in embed”, prefix)
}
}
return nil
}
“`
3. **添加文档注释**：提醒维护者不要修改 embed 指令
“`go
// 前端静态文件嵌入
// 注意：必须使用 all: 前缀，否则会排除以 _ 开头的文件
// Vite 动态路由生成的 chunk 文件名格式为 _id_-xxx.js
//go:embed all:embedded/dist
var embeddedFiles embed.FS
“`
## 参考
– [Go embed 文档](https://pkg.go.dev/embed)
– [Go 模块文件排除规则](https://go.dev/cmd/go/#hdr-Package_lists_and_patterns)