embed.FS 只能嵌入当前包路径及其子目录下的文件，不支持跨目录引用（如../）或相对路径跳转；路径大小写敏感且编译时固化，需统一小写命名并严格匹配；使用前须用http.FS包装才能用于http.FileServer。
embed.FS 不能直接读取子目录以外的文件
Go 的 embed.FS 在初始化时只绑定一个根路径，所有嵌入资源必须位于该路径下或其子目录中。比如用 //go:embed assets/*，那 assets 目录必须真实存在且在当前包路径下；如果写成 //go:embed ../config.yaml，编译会直接报错：pattern matches no files。
常见错误是误以为 embed 支持相对路径跳转（如 ../ 或 ./sub/../file），其实它只接受从当前包根开始的、扁平的路径模式匹配。
- ✅ 正确：当前包目录下有
templates/index.html，用//go:embed templates/* - ❌ 错误：试图
//go:embed ../../shared/logo.png—— embed 不支持跨包路径引用 - ⚠️ 注意：
//go:embed *不会递归匹配子目录下的文件，需显式写**（Go 1.16+ 支持）
embed 文件名大小写敏感且受操作系统影响
Windows 和 macOS 默认文件系统不区分大小写，但 embed.FS 在运行时按字面路径精确匹配 —— 这意味着你在 macOS 上开发时用 f.ReadFile("Assets/Icon.png") 可能成功，但部署到 Linux 服务器就报 fs: file does not exist，因为实际文件是 assets/icon.png。
根本原因是 embed 编译时把文件路径原样固化进二进制，不经过 OS 层路径标准化。
立即学习“go语言免费学习笔记（深入）”；
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 统一小写命名：建议所有嵌入资源路径全用小写字母 + 连字符，如
static/css/main.css - 读取时严格保持一致：调用
fs.ReadFile("static/css/main.css")，不要写成ReadFile("Static/CSS/main.css") - CI 中加校验：可用
go:embed模式配合embed.FS.ReadDir在测试中遍历检查路径是否存在
用 http.FileServer 服务 embed.FS 时需包装为 http.FileSystem
embed.FS 本身不是 http.FileSystem，不能直接传给 http.FileServer。必须用 http.FS 函数做一层转换，否则编译失败：cannot use embedded (type embed.FS) as type http.FileSystem。
这个转换看似简单，但有两个关键点：一是路径前缀处理，二是隐藏目录遍历风险。
- 必须用
http.FS(yourEmbedFS)包装，例如：http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(assets)))) - 若 embed 的是
assets/*，而你希望 URL/static/logo.png对应assets/logo.png，就得确保StripPrefix和http.FS的路径对齐 - 默认
http.FileServer允许目录列表（如访问/static/返回索引页），生产环境建议禁用：http.FileServer(http.FS(assets)).ServeHTTP配合自定义 handler 过滤strings.HasSuffix(r.URL.Path, "/")
调试 embed 资源缺失问题：用 ReadDir 看实际加载了什么
当 ReadFile 返回 “file does not exist” 却确认路径没错，最有效的方式是用 ReadDir 列出 embed.FS 实际包含的条目 —— 它能暴露路径拼写、大小写、通配符是否生效等隐性问题。
别依赖 IDE 或文件浏览器判断“文件是否存在”，embed 编译时只认 //go:embed 指令声明的路径模式和当时工作目录下的文件状态。
- 加一段调试代码：
files, _ := assets.ReadDir(".")<br>for _, f := range files {<br> fmt.Println(f.Name())<br>} - 注意：
ReadDir(".")列的是 embed 根下的直接子项；若 embed 的是templates/**，则templates是一个目录项，需再ReadDir("templates")才能看到内部文件 - 构建时加
-gcflags="-m" -ldflags="-s -w"可观察 embed 是否被内联进 binary（输出含inlining call to embed.Compile表示成功）
ls 确认当前 shell 位置。 
