embed.fs 需经 http.fs 包装才能用于 http.fileserver，且须注意路径匹配规则、空目录/隐藏文件被忽略、开发时无热更新等限制。
embed.FS 不能直接当 http.FileSystem 用
Go 的 embed.FS 本身不实现 http.FileSystem 接口，直接传给 http.FileServer 会编译报错：cannot use fs (type embed.FS) as type http.FileSystem。这是新手最常卡住的第一步。
必须用 fs.Sub 或 http.FS 包装一层：
import "embed"
import "net/http"
import "io/fs"
<p>//go:embed static/*
var staticFiles embed.FS</p><p>func main() {
// ✅ 正确：转成 http.FS
http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(staticFiles))))</p><pre class='brush:php;toolbar:false;'>// ❌ 错误：embed.FS 不是 http.FileSystem
// http.Handle("/static/", http.FileServer(staticFiles))}
-
http.FS是一个适配器函数，把实现了fs.FS的类型（比如embed.FS）转成http.FileSystem - 如果嵌入的是子目录（如
static/），建议先用fs.Sub(staticFiles, "static")切出子树，避免路径越界访问 - 注意
fs.Sub返回的仍是embed.FS，仍需套一层http.FS
嵌入空目录或隐藏文件会被忽略
//go:embed 指令不会打包空目录，也不会包含以 . 或 _ 开头的文件（如 .gitignore、_config.yml），这和大多数构建工具的行为一致，但容易导致前端资源加载失败却查不出原因。
立即学习“go语言免费学习笔记（深入）”；
- 检查是否真有文件被嵌入：用
fs.ReadDir打印目录结构验证 - 若需嵌入 dotfile，改名（如
dot_gitignore）再在代码里重映射逻辑 - 空目录问题无绕过办法——Go embed 不支持“占位”，得至少放一个空文件（如
static/css/.keep）
开发时热更新失效，但不是 embed 的锅
用 embed 后，修改 static/ 下的 HTML/CSS/JS 文件，go run 不会自动重新读取——因为 embed 是编译期行为，源文件变更不触发重编译。这不是 bug，是设计使然，但容易让人误以为“嵌入失败”。
- 开发阶段建议：用条件编译区分 embed 和本地文件系统
- 加个
-tags dev构建标签，在开发时跳过 embed，直接读磁盘路径 - 生产构建必须显式运行
go build，go run会重新编译，但每次改资源都要等编译，体验差
embed 路径匹配是前缀匹配，不是 glob 全匹配
//go:embed assets/** 看起来像通配，但 Go embed 实际只做简单前缀展开，不支持 ** 递归或 ? 单字符匹配。写错路径模式会导致静默失败——没报错，但 embed.FS 里压根没有文件。
-
//go:embed static/*→ 匹配static/a.txt、static/b.js，不匹配static/sub/c.css -
//go:embed static/**→ Go 1.22+ 支持，但仅限于**在末尾；assets/**/index.html仍不合法 - 最稳写法：明确列出顶层目录，多行写多个
//go:embed，比如分别写static/css/*、static/js/*
路径写错时，fs.ReadDir 返回空切片且无错误，得靠日志或调试确认内容是否存在——这点最容易被忽略。
