embed.fs只能嵌入当前包或其子目录下的文件，路径须为相对包根的静态字面量，区分大小写；嵌入内容编译进二进制，readfile返回只读[]byte；需用fs.sub配合http.fileserver服务静态资源；build tag会导致整个文件不参与编译，使嵌入失效。
embed.FS 不能直接读取子目录外的文件
Go 的 embed.FS 只能嵌入当前包（或其子目录）下的文件，路径必须是相对包根目录的静态路径。如果你在 main 包里写 //go:embed assets/**，但 assets/ 实际在上层目录（比如和 cmd/ 并列），编译会直接报错：pattern matches no files。
常见错误现象：本地 go run . 能跑，CI 构建失败；或者 embed.FS.ReadFile("config.yaml") panic 报 file does not exist，其实是因为路径没对齐包结构。
- 把要嵌入的文件移到当前包目录下（例如
./internal/assets/或./web/static/），再用//go:embed web/static/** - 嵌入时路径区分大小写，Linux/macOS 下尤其敏感 ——
//go:embed Static/**不会匹配static/ - 不能用变量、拼接字符串或函数调用构造嵌入路径，
//go:embed后面必须是字面量
embed.FS.ReadFile 返回的 []byte 是只读内存副本
embed.FS 嵌入后所有文件内容被编译进二进制，ReadFile 返回的是只读切片，修改它不会影响原始数据，也不会触发 panic，但改了也没用 —— 下次再 ReadFile 还是原样。
使用场景：适合配置加载、模板渲染、前端资源注入等「读多写无」场景；不适合需要运行时动态修改文件内容的逻辑（比如缓存写入、日志追加）。
- 如果需要可变内容，先
ReadFile拿到[]byte，再append或copy到新切片操作 - 注意大文件（>1MB）嵌入后会显著增大二进制体积，且无法按需加载 ——
embed.FS没有流式读取接口 -
ReadDir和Open返回的fs.File也只支持Read，不支持Write、Seek等
用 http.FileServer 配合 embed.FS 服务前端静态资源
很多人想用 embed.FS 替代传统 dist/ 目录部署，但直接传 embed.FS 给 http.FileServer 会 404 —— 因为默认 http.FileServer 要求路径以 / 开头，而 embed.FS 的根是空路径。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
正确做法是用 fs.Sub 剥离一层，或者用 http.FS 包装：
assets, _ := fs.Sub(content, "web/static")
http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(assets))))
关键点：
-
fs.Sub第二个参数不能以/开头，也不能是.或.. - 如果嵌入路径是
web/static/**，浏览器访问/static/main.js才能命中，不是/main.js - 生产中建议加
http.MaxBytesReader限制上传，因为embed.FS本身不处理写请求，但FileServer默认允许 PUT/POST（虽然会失败）
build tags 和 embed 冲突会导致文件“消失”
当代码同时用了 //go:build 和 //go:embed，且 build tag 不满足时，嵌入语句会被整个忽略 —— 编译器不会报错，但对应 embed.FS 变量变成空，ReadFile 必然失败。
典型场景：你写了 //go:build !test 在 embed 上方，结果测试时 go test -tags=test，文件就没了。
- embed 指令必须和它修饰的变量在同一文件、且紧挨着变量声明（中间不能有空行或注释）
- build tag 影响的是「整个文件是否参与编译」，不是单独关掉 embed；所以别把 embed 放在条件编译块里
- 调试方法：用
go tool compile -S main.go | grep embed看是否生成了 embed 符号
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
