go:embed路径必须相对于go.mod所在模块根目录，而非.go文件位置；需字面量路径、无./或../、文件真实存在且非空，且//go:embed指令须紧邻var声明。
go:embed 是 Go 1.16+ 唯一官方支持、无需额外工具的静态资源嵌入方式。它不是“打包成 zip”，而是把文件内容直接写进二进制只读段，运行时无磁盘依赖、单文件分发即开即用。
为什么 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 不是路径写错，而是没做子树切分或类型转换。
-
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路径一致 - 如果嵌入路径是
templates/，那 glob 就写templates/*.html，不能漏前缀 - 多个模板互相
{{template "xxx"}}引用时，所有文件必须在同一embed.FS实例下，否则解析失败
go.mod 目录算起，不是当前 .go 文件位置，也不是你执行 go build 的终端路径。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
