embed路径必须相对于声明它的.go文件所在目录，而非项目根目录或build目录；需确保文件真实存在、大小写严格匹配，且避免空目录、隐藏文件（.开头）和下划线开头文件被静默跳过。
embed 路径必须相对于当前 .go 文件，不是项目根目录
很多人在 //go:embed 后写 static/*，结果编译报 pattern matches no files，根本原因不是文件不存在，而是路径起点错了——embed 的路径解析始终以声明该指令的 .go 文件所在目录为基准，不是 go build 所在目录，也不是 main.go 位置。
常见错误场景：
- 把
//go:embed static/*写在handlers/main.go里，但static/在项目根目录 → 实际找的是handlers/static/ - 用 IDE 右键 Run，工作目录是子模块路径，而
static/在上层 → embed 根本看不到 - Windows 下写了
static\*.js→ embed 只认/，反斜杠直接被忽略或导致匹配失败
正确做法：统一把静态资源放在和 embed 声明文件同级的子目录下（如 ui/），或显式用 ../static/*（不推荐，因 embed 不支持 ..）；更稳妥的是把 embed 声明挪到项目根目录的 embed.go 中，再放 //go:embed ui/**。
embed.FS 必须经 http.FS 包装才能传给 http.FileServer
http.FileServer 接口要求类型是 http.FileSystem，而 embed.FS 实现的是 fs.FS。直接传会编译报错：cannot use assets (type embed.FS) as type http.FileSystem。
必须加一层转换：
-
http.FileServer(http.FS(assets))—— 最简写法，适用于嵌入路径与 URL 路径一致的情况 -
http.FileServer(http.FS(fs.Sub(assets, "ui")))—— 当你嵌了ui/目录，但想让/static/请求映射到ui/内容时用 - 千万别漏掉
http.StripPrefix：比如挂载点是/static/，就得http.StripPrefix("/static/", ...)，否则请求/static/app.js会去查app.js（没带前缀）
注意：fs.Sub 返回的仍是 embed.FS，仍需套 http.FS()；两次包装不会出错，但多一层冗余。
模板文件不能用 template.ParseFiles，得用 template.ParseFS
template.ParseFiles("templates/index.html") 底层调用 os.Open，而 embed 文件不在磁盘上，必然 panic：open templates/index.html: no such file or directory。
正确路径只有两条：
- 单文件模板：先
fs.ReadFile(assets, "templates/index.html")，再template.Must(template.New("index").Parse(string(b))) - 多文件 + 嵌套引用（如
{{template "header"}}）：必须用template.ParseFS，它原生接受fs.FS，且能自动解析相对路径和{{template}}关系 - 别手动拼路径字符串传给
ParseFS：如果//go:embed templates/**，那ParseFS(assets, "templates/*.html")才对；写成"*.html"就会找不到
空目录、隐藏文件、大小写敏感这些细节容易漏检
embed 默认跳过三类内容：空目录、以 . 开头的文件（如 .gitignore）、以 _ 开头的文件（如 _config.yml）。前端构建产物里常有 .DS_Store 或 _redirects，嵌入后缺失却不报错，上线才发现 404。
调试建议：
- 用
fs.WalkDir(assets, ".", func(path string, d fs.DirEntry, err error) { ... })打印所有嵌入路径，确认是否符合预期 - Linux/macOS 上路径大小写敏感：嵌了
Assets/，代码里却读assets/logo.png→no such file - 嵌入大量图片/字体时二进制体积暴涨，UPX 可压但 macOS Apple Silicon 签名可能失效，上线前务必验证
真正卡住人的从来不是语法，而是路径是否真实存在、大小写是否完全一致、以及那个被静默跳过的 .gitkeep 文件——它连提醒都不会给你。
