embed 是一套独立的编译期契约，路径必须为相对于模块根目录的字面量、真实存在且大小写敏感；声明为 string/[]byte 仅支持单文件，embed.FS 支持通配符但需用 fs.Sub 和 http.FS 适配 HTTP 服务。
不能靠“学语言”顺带掌握 embed —— 它是一套独立的编译期契约，规则硬、容错低、报错静默，必须按规范逐条对齐才能生效。
embed 路径为什么总报 fs.ErrNotExist？
不是文件没找到，是嵌入根本没发生。embed 对路径有三重硬约束：
• 路径必须是相对 go build 执行目录的字面量，不能含 ./、../ 或变量拼接
• //go:embed assets/logo.png 中的 assets/logo.png 必须真实存在，且位于当前模块根目录下（不是 .go 文件所在目录）
• 若 .go 文件在 cmd/myapp/main.go，想嵌 ui/index.html，路径仍得写 ui/index.html，不是 ../ui/index.html
常见踩坑点：
• 写成 //go:embed ./ui/** → 编译失败：cannot embed relative path
• ui/ 是空目录 → embed 静默跳过，运行时读取返回 fs.ErrNotExist
• Windows 下文件名大小写不敏感，但 embed 路径区分大小写：Index.html ≠ index.html
string、[]byte 和 embed.FS 该选哪个？
类型选择直接决定能否编译通过：
• 声明为 string 或 []byte：只能匹配单个文件，且不能用通配符（//go:embed assets/* 会报错）
• 声明为 embed.FS：支持通配符（** 递归，* 单层），但后续读取必须用 fs.ReadFile 或 fs.Open，路径需严格匹配嵌入结构
立即学习“go语言免费学习笔记（深入）”；
例如：
• //go:embed config.yaml + var cfgYAML []byte → 直接可用，适合小配置或图标
• //go:embed ui/** + var uiFS embed.FS → 后续读取 ui/index.html 时，路径必须带前缀，不能只写 index.html
HTTP 服务怎么把嵌入资源正确暴露出去？
直接传 embed.FS 给 http.FileServer 会编译失败：
• 错误写法：http.FileServer(uiFS) → cannot use uiFS (type embed.FS) as type http.FileSystem
• 正确链路：http.FileServer(http.FS(fs.Sub(uiFS, "ui")))，其中 fs.Sub 切出子树，http.FS 做类型适配
若前端请求路径是 /static/main.js，而资源实际在 ui/static/main.js：
• 必须加 http.StripPrefix("/static/", ...)，否则请求路径多了一级前缀，查不到文件
• MIME 类型不会自动推断，http.FileServer 默认逻辑（如根据扩展名设 Content-Type）在 embed 下仍有效，但依赖路径后缀是否匹配
调试 embed 最有效的手段是什么？
别猜路径，用代码验证：
• 用 fs.WalkDir(uiFS, ".", func(path string, d fs.DirEntry, err error) { fmt.Println(path) }) 打印所有嵌入路径，确认结构是否符合预期
• 判断文件是否存在时，必须用 errors.Is(err, fs.ErrNotExist)，os.IsNotExist(err) 对 embed 返回 false
• 修改 //go:embed 后务必 clean 构建缓存：go clean -cache -modcache，否则旧嵌入内容可能残留
最易被忽略的是：embed 是编译期行为，没有热重载、不响应文件改动、不兼容传统文件操作（如 os.Stat），所有路径和结构必须在构建那一刻就确定且稳定。
