go:embed 只能嵌入编译时存在的只读文件或目录，路径须为相对于 go build 目录的静态路径；不支持运行时路径、符号链接（未展开）、.. 跳转、设备文件、管道或网络资源。
go:embed 能嵌什么，不能嵌什么
直接说结论：go:embed 只能嵌入编译时存在的**只读文件或目录**，且路径必须是相对于 go build 执行目录的静态路径。它不支持运行时动态路径、符号链接（除非加 //go:embed 注释前用 realpath 展开）、.. 向上跳转，也不支持嵌入设备文件、管道或网络资源。
常见错误现象：pattern matches no files —— 多半是路径写错了，或者文件在 go build 当前目录下根本不存在；cannot embed relative path —— 用了 ./assets 这种带 . 的写法，必须写成 assets 或 static/** 这类无前缀形式。
- 推荐把资源放在项目根目录下固定子目录，比如
ui/、templates/、config/ - 嵌入整个目录时用通配符：
//go:embed templates/*，注意*不递归，要递归得写templates/** - 如果嵌入单个文件，路径名必须完全匹配，大小写敏感（Windows/macOS 上容易因忽略大小写误以为成功）
embed.FS 怎么读取文件内容，和 os.ReadFile 有啥区别
embed.FS 是只读文件系统接口，不是普通磁盘路径。你不能把它当 string 拼接进 os.ReadFile，也不能用 ioutil.ReadFile 直接读——必须用 fs.ReadFile 或 fs.ReadDir 等 fs 包函数操作。
典型错误：写 os.ReadFile("templates/index.html") —— 运行时报 no such file or directory，因为文件没在磁盘上，而在二进制里。
立即学习“go语言免费学习笔记（深入）”；
- 正确做法是先声明
var templates embed.FS，再调用fs.ReadFile(templates, "templates/index.html") - 路径参数是相对路径，且必须和
//go:embed注释中声明的路径前缀对齐（比如//go:embed templates/*，那读取时就得用"templates/xxx"） - 性能上，
embed.FS读取是内存拷贝，没有 I/O 开销，但每次ReadFile都会复制一份字节切片；如需多次访问同一内容，建议缓存[]byte或提前解析成结构体
嵌入模板文件时，html/template 为啥报 “template: not found”
因为 template.ParseFS 要求路径格式和 embed.FS 中的路径严格一致，且默认不递归查找子目录里的模板。如果你嵌了 templates/**，但用 tmpl.ParseFS(templates, "templates/*.html")，却漏掉了 ParseFS 第二个参数的 glob 模式写法，就会找不到。
常见错误：直接传 "templates" 当模式，但 ParseFS 第二个参数不是根路径，是匹配规则。
- 正确写法：
template.ParseFS(templates, "templates/*.html")或"templates/**/*.html"（Go 1.16+ 支持双星号递归） - 注意：如果模板里用
{{template "header"}}引用其他模板，那些被引用的模板也必须落在 glob 匹配范围内，否则运行时报template: ... is undefined - 调试技巧：用
fs.ReadDir打印所有嵌入的路径，确认实际加载了哪些文件
交叉编译时 embed 资源丢失或路径错乱
根本原因：go:embed 解析路径是在 go build 执行时做的，不是在源码分析阶段。如果你在 CI 或 Docker 构建中切换了工作目录，或者用 go build -o /tmp/app ./cmd 从非项目根目录执行，embed 就找不到文件。
错误现象：本地能跑，CI 构建后运行 panic：pattern matches no files 或读取返回空内容。
- 构建命令必须在项目根目录下执行，且确保
embed注释指向的路径存在（可用ls -R | grep your-dir快速验证） - Dockerfile 中避免
WORKDIR /app后直接COPY . .再go build—— 要么COPY到根目录，要么显式WORKDIR /src并保证资源目录也在/src下 - Go 1.21+ 加了
go:embed路径检查警告，但默认不报错；可通过GO111MODULE=on go list -f '{{.EmbedFiles}}' .查看实际嵌入了哪些文件，用于排查
最易被忽略的一点：嵌入的文件内容是编译时快照，改了资源不重新 go build，二进制里还是旧内容——连热重载都救不了，必须重建。
