Go 1.16+ embed 包嵌入文件需满足路径为包根相对字面量、紧贴声明 embed.FS 变量、用 fs.ReadFile 读取且路径匹配嵌入结构、HTTP 服务需用 http.FS 转换并 StripPrefix，大小写敏感且空目录/隐藏文件静默跳过。
Go 1.16+ 的 embed 包能真正把文件编译进二进制，但不是“写了 //go:embed 就一定生效”——它对路径、声明位置、变量类型和调用方式有硬性约束，任一环节出错都会静默失败或编译报错。
嵌入路径必须是相对包根的字面量字符串
你不能拼接、不能用变量、不能跨目录、不能带 ./ 前缀。比如当前 .go 文件在 cmd/myapp/main.go，想嵌入 assets/logo.png，就必须确保该文件真实存在于 cmd/myapp/assets/logo.png，然后写：
//go:embed assets/logo.png var logoFS embed.FS
以下写法全错：
-
//go:embed ./assets/logo.png（./前缀被拒绝） -
//go:embed assets/*但assets/是空目录（embed 会跳过，不报错） -
//go:embed "assets/" + env（变量拼接 → 编译失败：go:embed cannot embed variable） -
//go:embed github.com/myorg/mylib/static/**（跨模块，默认不可见）
embed.FS 变量声明必须紧贴 //go:embed 指令
//go:embed 不是注释，是编译指令，只对**紧跟着的包级变量声明**生效，中间不能有空行、注释或其它语句。
立即学习“go语言免费学习笔记（深入）”；
✅ 正确：
//go:embed assets/* var staticFS embed.FS
❌ 错误（空行导致失效）：
//go:embed assets/* <p>var staticFS embed.FS
❌ 错误（中间夹了注释）：
//go:embed assets/* // 这行注释会让 embed 失效 var staticFS embed.FS
一旦断开，staticFS 就是空的 embed.FS，后续 fs.ReadFile(staticFS, "assets/x.js") 必然返回 fs.ErrNotExist。
读取 embed.FS 必须用 fs.ReadFile 或 fs.Open，且路径要匹配嵌入结构
embed.FS 是虚拟文件系统，路径是相对于 //go:embed 声明的根。比如：
//go:embed frontend/* var frontendFS embed.FS
那 frontend/index.html 在 FS 中的路径就是 index.html，不是 frontend/index.html —— 除非你显式保留前缀：
//go:embed frontend/** var frontendFS embed.FS // 注意：** 才递归包含子目录
此时路径才是 frontend/index.html。常见错误：
- 用
os.Open("frontend/index.html")→ 查磁盘，和 embed 无关 - 用
fs.ReadFile(frontendFS, "frontend/index.html")但声明是//go:embed frontend/*→ 路径不匹配，报file does not exist - 判断文件是否存在用
os.IsNotExist(err)→ 总是false，必须用errors.Is(err, fs.ErrNotExist)
HTTP 服务中要用 http.FS 包装 embed.FS
embed.FS 本身不实现 http.FileSystem 接口，直接传给 http.FileServer 会编译失败：
cannot use frontendFS (type embed.FS) as type http.FileSystem
正确写法分两步：
- 用
http.FS(frontendFS)转换类型 - 用
http.StripPrefix对齐 URL 路径（如浏览器访问/static/main.js，实际读的是main.js）
示例：
http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(frontendFS))))注意：http.FileServer 默认不列目录，访问 /static/ 返回 404 是正常的；如果需要 fallback 到首页（SPA 场景），得自己加 handler。
最容易被忽略的是：嵌入路径区分大小写，而 Windows 开发者常因本地不报错就误以为 OK，结果 Linux CI 构建失败；还有空目录、隐藏文件（.gitignore）、构建 tag 导致整个文件未参与编译——这些都不会报错，但资源就是没进去。
