embed 只能嵌入当前包目录下的静态文件，需用 //go:embed 显式声明路径；读取时必须检查 error，避免 fs.ErrNotExist 导致 panic；SQL 文件应小写+下划线命名，按前缀排序执行；需适配迁移库或手动维护版本记录。
embed 不能直接嵌入 SQL 文件的常见误解
很多人试过 embed 后发现读出来是空字符串或 panic，根本原因不是语法错，而是没理解 Go 的 embed 规则：它只认「包路径下的静态文件」，且必须用 //go:embed 指令显式声明——SQL 文件如果不在当前包目录下、路径写错、或用了通配符但没匹配到任何文件，embed.FS 就会是空的。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- SQL 文件必须放在当前
.go文件所在目录（或子目录），不能跨包引用 -
//go:embed后面的路径是相对于该.go文件的位置，不是项目根目录 - 别用
//go:embed *.sql试图批量加载——Go 1.16+ 支持通配符，但要求至少匹配一个文件，否则编译失败 - 推荐先用
//go:embed migrations/*.sql，再在代码里用fs.Glob列出所有匹配项
如何安全读取嵌入的 SQL 文件并避免 panic
最常踩的坑是直接调用 fs.ReadFile("migrations/001_init.sql") 却没检查 error——嵌入失败时返回的是 fs.ErrNotExist，不是 nil，不判错就 panic。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 永远用
if data, err := fs.ReadFile("path/to/file.sql"); err != nil包裹读取逻辑 - SQL 文件名建议全小写 + 下划线，避免大小写敏感问题（Windows/macOS 可能不报错，Linux 构建会失败）
- 如果多个 SQL 文件有执行顺序依赖，别靠文件名排序——用前缀如
001_、002_，然后用strings.TrimPrefix+strconv.Atoi解析序号 - 别把 SQL 当二进制读；默认是 UTF-8，但若文件含 BOM 或非标准换行符，
string(data)可能导致迁移失败，建议用bytes.TrimSpace清理首尾空白
embed 和 sql-migrate / golang-migrate 怎么配合用
原生 embed 不提供迁移版本管理、回滚、状态检查等功能，直接硬塞 SQL 到 sql.DB.Exec 是危险的。必须和迁移库桥接。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
embed.FS加载全部 SQL 内容后，手动构造migrate.Migration列表（以golang-migrate/migrate/v4为例） - 每个 SQL 文件需对应一个
migrate.Migration实例，Up字段填string(data)，Down可设为""或单独的 rollback SQL - 注意：golang-migrate 的
source.Driver接口不接受embed.FS，得自己实现一个io/fs.FS到migrate.Source的适配器 - 更轻量的做法是绕过 migrate 库，用
embed.FS+database/sql手动执行，但必须自己维护已执行 migration 的记录表（比如schema_migrations）
构建后 SQL 内容不可变，但运行时可能被覆盖
embed 的内容在编译时固化进二进制，这点很可靠。但容易被忽略的是：如果程序启动时还去读取同名磁盘文件（比如为了开发调试加了 fallback 逻辑），反而会破坏一致性。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 开发阶段可用
os.ReadFilefallback，但上线前必须删掉，或用build tag隔离（如//go:build !prod） - 不要在 embed 路径里混用相对路径和绝对路径——例如
fs.ReadFile("migrations/../sql/init.sql")在 embed 中非法，编译报错 - SQL 文件体积大（>1MB）时，嵌入会导致二进制显著膨胀，且每次修改都触发全量重编译；可考虑只 embed 关键初始化 SQL，其余用远程加载
嵌入 SQL 看似简单，真正难的是让嵌入行为在 dev/test/prod 三套环境里表现一致，而不是某处多一个空格、少一个斜杠就让迁移卡住。
