go 的 embed 是唯一能真正实现“单文件交付”的官方机制，但必须严格按编译期路径规则使用；路径须相对于声明 //go:embed 的 .go 文件目录，windows 用 /，禁用 ./ 或 ../，大小写敏感，embed.fs 需经 http.fs() 转换才能用于 http 服务，模板须用 parsefs 或 readfile，调试需 readdir 并用 errors.is(err, fs.errnotexist) 判断。
Go 的 embed 是唯一能真正实现“单文件交付”的官方机制，但必须严格按编译期路径规则使用；用错就编译失败或运行时 fs.ErrNotExist，没有中间状态。
//go:embed 路径必须相对于 .go 文件所在目录
嵌入失败最常见原因不是文件不存在，而是路径解析起点错了。Go 不会从项目根、main.go 或当前工作目录找文件，只认声明 //go:embed 的那个 .go 文件的目录。
- 如果你在
cmd/app/main.go里写//go:embed assets/*，它只找cmd/app/assets/，不是项目根下的assets/ - Windows 上必须用
/，写assets\logo.png会被忽略（编译不报错，但匹配不到） -
./assets/或../assets/直接编译报错：embed 明确禁止相对路径符号 - 路径区分大小写：
Logo.png和logo.png是两个文件，嵌入声明必须完全一致
embed.FS 必须经 http.FS() 转换才能用于 HTTP 服务
embed.FS 实现的是 fs.FS 接口，而 http.FileServer 需要 http.FileSystem——类型不兼容，直接传会编译失败。
- 错误写法：
http.FileServer(staticFiles)→ 报错cannot use staticFiles (type embed.FS) as type http.FileSystem - 正确写法：
http.FileServer(http.FS(staticFiles))，这是不可省略的桥接步骤 - 如果想把
ui/dist/映射到/static/，得先fs.Sub(staticFiles, "ui/dist")切出子树，再套http.FS() - 漏掉
http.StripPrefix("/static/", ...)会导致请求路径多一层前缀，比如/static/main.js去查main.js而不是ui/dist/main.js，必然 404
模板渲染不能用 template.ParseFiles
template.ParseFiles 底层调用 os.Open，而 embed 文件根本不在磁盘上——它只存在于二进制只读段，所以一定会 panic。
- 正确方式是用
template.ParseFS（Go 1.16+）：template.Must(template.New("").ParseFS(staticFiles, "templates/*.html")) - 或者手动读取：
data, _ := staticFiles.ReadFile("templates/index.html")，再template.Must(template.New("").Parse(string(data))) - 注意通配符：
templates/*.html只匹配一级，templates/**.html才递归匹配子目录（需 Go 1.17+） - 路径必须完整：如果嵌入时是
//go:embed templates/*，那么文件在 FS 中的路径就是templates/index.html，不是index.html
调试 embed 是否生效的唯一可靠方法
别靠猜，也别只看编译是否通过。嵌入失败常常静默发生（比如目录为空、文件名大小写不对、以 . 或 _ 开头被跳过），最终表现为 fs.ErrNotExist。
- 加一行调试代码：
entries, _ := staticFiles.ReadDir(".")，然后fmt.Println(entries)，确认实际嵌入了哪些路径 - 判断错误必须用
errors.Is(err, fs.ErrNotExist)，不能用os.IsNotExist(err)——后者对 embed 返回false - 大文件（如视频、PDF）慎 embed：它直接增大二进制体积，且无法按需加载；小资源（模板、CSS、图标）才适合
- 嵌入后资源不可写、不可热更新，改了就得重新编译——这既是限制，也是部署一致性的保障
最容易被忽略的点是：embed 的路径规则和类型桥接不是“可选优化”，而是硬性契约。编译期就定死，运行时没商量余地。写错一个斜杠、少一层 http.FS()、路径大小写差一个字母，结果都是 404 或 panic，不会给你第二次机会。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
