Go的embed是编译期资源固化机制，非静态化工具；它将文件内容写入二进制只读段，运行时无I/O、无路径依赖，但不支持热更新、不接受变量路径、不兼容传统文件系统操作。
Go 的 embed 不是“静态化”工具，而是编译期资源固化机制——它把文件内容直接写进二进制只读段，运行时无 I/O、无路径依赖，但也不支持热更新、不接受变量路径、不兼容传统文件系统操作。
嵌入单个文件：用 []byte 或 string 最快，但路径必须字面量
适合配置、小图标、模板片段等固定内容。声明和使用必须严格对齐：
-
//go:embed指令必须紧邻变量声明，中间不能有空行或注释 - 变量类型只能是
[]byte、string或embed.FS，不能是*os.File或其他自定义类型 - 路径必须是相对当前
.go文件的静态字符串，比如"config.yaml"，不能是dir + "/config.yaml"或"./config.yaml" - 若文件在
internal/assets/下，而.go在cmd/app/，则需把文件移到同包下，或改用embed.FS+ 显式子目录声明
示例（正确）：
//go:embed config.yaml
var configYAML []byte
func main() {
fmt.Println(string(configYAML))
}
嵌入整个前端目录：用 embed.FS + fs.Sub 控制挂载点
常见于 dist/ 或 web/static/ 目录。关键不是“怎么嵌”，而是“怎么让请求路径和嵌入路径对上”：
立即学习“go语言免费学习笔记（深入）”；
-
//go:embed web/dist/**才能递归包含子目录；web/dist/*只匹配一级文件 - 嵌入后，
web/dist/index.html在 FS 中的路径就是web/dist/index.html，不是index.html - 想让
/static/main.js访问到web/dist/main.js，必须先fs.Sub(fsys, "web/dist")切出子树，再http.FS()包装 - 漏掉
http.StripPrefix("/static/", ...)会导致请求路径多了一层前缀，查不到文件
错误写法（直接传 embed.FS）会编译失败：cannot use fsys (type embed.FS) as type http.FileSystem
读取失败总是 fs.ErrNotExist，别用 os.IsNotExist
这是最常被忽略的类型差异。嵌入文件不存在时，embed.FS.ReadFile 返回的是 *fs.PathError，其底层 error 是 fs.ErrNotExist：
- ✅ 正确判断：
if errors.Is(err, fs.ErrNotExist) - ❌ 错误判断：
os.IsNotExist(err)—— 对 embed 返回false，永远走不到分支 - Windows 上大小写不敏感，但 embed 路径区分大小写，
Logo.png≠logo.png - 调试建议：用
fs.ReadDir(fsys, ".")打印根目录结构，确认实际嵌入了哪些路径
HTTP 服务中嵌入资源：必须过 http.FS，且 MIME 类型要自己管
http.FileServer 默认逻辑（如自动加 Content-Type）在 embed 下不会触发，浏览器可能把 .js 当成 text/plain 拒绝执行：
- 必须用
http.FS(fsys)包装，不能直接传embed.FS - 若用自定义 handler（非
http.FileServer），需手动调用http.DetectContentType或按扩展名映射 MIME 类型 -
template.ParseFiles会 panic，因为它内部调用os.Open；必须先fs.ReadFile再template.New().Parse(string(b)) - 构建时路径失效：
os.Executable()找不到嵌入文件，所有读取必须走embed.FS实例
真正容易踩的坑不在语法，而在路径思维惯性——你写的每一条 ReadFile("...")，都必须和 //go:embed ... 声明的路径完全一致（包括大小写、斜杠方向、前缀层级），少一个字符，运行时就 fs.ErrNotExist。
