Go 1.16+ 唯一官方支持的静态资源嵌入方式是 go:embed，它将文件内容直接写入二进制只读段，实现无磁盘依赖、单文件分发；失败主因仅两个：路径不合法（须相对于 go.mod 根目录、禁用 .//..//变量、文件真实非空）或声明不合规（//go:embed 必须紧邻 var 声明、不可有空行或注释）。
Go 1.16+ 唯一官方支持、无需额外工具的静态资源嵌入方式是 go:embed，它把文件内容直接写进二进制只读段，运行时无磁盘依赖、单文件即开即用；其他方案（如 statik、packr）已归档或需代码生成，不推荐新项目使用。
为什么 //go:embed 编译失败或静默忽略？
根本原因只有两个：路径不合法，或声明不合规。
-
//go:embed路径必须是相对于go.mod所在模块根目录的字面量，不能含./、../或变量；写//go:embed ./ui/*直接报错，得写//go:embed ui/* - 路径必须真实存在且非空——
ui/下若全是空目录，embed会跳过整个路径，不报错也不嵌入 -
//go:embed指令必须紧挨着var声明，中间不能有空行、注释或其它语句 - 以
.或_开头的文件（如.gitignore、_config.yml）默认被忽略；前端构建产物里若有.nojekyll就会丢
fs.ReadFile 报 no such file or directory 怎么办？
这不是磁盘路径问题，是你误把 embed.FS 当成了本地路径前缀。
- 错误写法：
os.ReadFile("ui/index.html")→ 文件不在磁盘，必然失败 - 正确写法：
fs.ReadFile(assetsFS, "ui/index.html")，其中assetsFS是你声明的embed.FS变量 - 路径必须严格对齐：
//go:embed ui/*→ 读取时必须带ui/前缀；//go:embed static/**→ 读取时仍需写static/css/main.css - 判断文件缺失要用
errors.Is(err, fs.ErrNotExist)，不是os.IsNotExist(err)
用 http.FileServer 提供嵌入资源时为何 404？
常见 404 不是路径写错，而是没做子树切分或类型转换。
立即学习“go语言免费学习笔记（深入）”；
-
http.FileServer(assetsFS)编译失败：类型不匹配，embed.FS不是http.FileSystem - 正确写法：
http.FileServer(http.FS(assetsFS))——http.FS()是必需的适配器 - 如果嵌入的是
ui/目录，但想让/对应ui/内容，必须先切子树：fs.Sub(assetsFS, "ui")，再套http.FS() - 若 URL 前缀是
/static/，而资源在public/目录下，链路是：http.StripPrefix("/static/", http.FileServer(http.FS(fs.Sub(assetsFS, "public")))) - 访问
/返回 404 是正常行为：http.FileServer默认不生成目录列表
template.ParseFS 为什么总 panic？
template.ParseFiles 底层调用 os.Open，对 embed.FS 完全无效。
- 别用
ParseFiles，改用template.ParseFS（Go 1.16+ 原生支持） - 传参时注意路径匹配：
template.ParseFS(assetsFS, "templates/*.html")中的 glob 必须和//go:embed路径一致 - 如果嵌入的是
ui/，但模板在ui/templates/，则//go:embed ui/templates/*.html和template.ParseFS(assetsFS, "ui/templates/*.html")必须严格对应 - 若模板含
{{template}}调用，所有被引用的子模板也必须在 glob 范围内，否则运行时报template: : "xxx" is undefined
最易被忽略的点是路径起点：它始终是模块根（go.mod 所在目录），不是 .go 文件位置，也不是终端当前工作目录；CI 构建时若 go build 不在模块根执行，embed 就会失效——这点在自动化流程中尤其关键。
