根本原因是 migrate 默认从当前工作目录找 ./migrations，而 CI 环境往往不在项目根目录执行或未复制迁移文件；需确认 cd 到根目录、显式复制 migrations、用绝对路径调用，避免依赖 embed 或 statik。
为什么 migrate 命令在 CI 里总报错“no such file or directory”
根本原因是 migrate 默认从当前工作目录找 ./migrations，而 CI 环境（比如 GitHub Actions 的 run 步骤）往往不在项目根目录执行，或没把迁移文件一起复制进去。
- 确认 CI 构建步骤是否显式
cd到项目根路径，比如cd /workspace/myapp - 检查是否遗漏
cp -r migrations/ $ARTIFACT_DIR/类操作——migrate不会自动打包嵌入 Go 二进制，它只读磁盘上的 SQL 文件 - 用绝对路径调用更稳妥：
migrate -path /home/runner/work/myapp/myapp/migrations -database "postgres://..." up - 别依赖
go:embed或statik：官方migrateCLI 不支持从 embed.FS 加载，硬塞会静默失败
migrate 的 -source 和 -path 参数到底怎么选
这两个参数经常被混用，但语义完全不同：-path 是本地文件系统路径（最常用），-source 是通用 URL 格式，支持 file://、github://、git::https:// 等——但 CI 中几乎只用 -path。
-
-path ./migrations：推荐，简洁明确，要求路径存在且可读 -
-source file://./migrations：等价于上者，但多一层解析开销，无实际优势 -
-source github://myorg/myrepo//migrations：适合共享迁移模板，但 CI 中需配置 SSH key 或 token，容易因权限失败 - 避免
-source http://...：HTTP 不支持 HEAD 检查版本顺序，migrate会直接 panic
CI 中执行 migrate up 前必须验证的三件事
不是所有“up 成功”都代表数据库就绪；很多 CI 流水线卡在后续服务启动，其实是因为迁移没真正生效。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 数据库连接串必须带
sslmode=disable（或对应 CA 配置），否则 PostgreSQL 客户端在 CI 容器里常因证书缺失拒绝连接 - 确保
migrate status在up后返回 0 且末行是all migrations applied，而不是停在某条pending - 加一句简单校验：
psql -U user -d db -c "SELECT COUNT(*) FROM schema_migrations;"，确认表已建且有记录——有些旧版migrate在空库首次运行时漏建该表
Go 项目里用 github.com/golang-migrate/migrate/v4 库做内嵌迁移的风险点
虽然文档说支持 “in-memory” 迁移，但实际在 CI 中绑定 Go 代码调用，反而放大不确定性：版本锁不牢、驱动注册遗漏、错误日志被吞。
立即学习“go语言免费学习笔记（深入）”；
- 别在
main.go里写migrate.New("file://migrations", "...")：路径相对位置随go run目录漂移，CI 中极难调试 - PostgreSQL 驱动必须显式导入：
_ "github.com/golang-migrate/migrate/v4/database/postgres"，漏掉就 panic 报unknown driver "postgres" - 优先用 CLI 而非 SDK：CI 流水线里
curl -L https://github.com/golang-migrate/migrate/releases/download/v4.15.2/migrate.linux-amd64.tar.gz解压调用，版本可控、行为稳定
迁移文件名里的时间戳顺序不能靠人肉保证，migrate 严格按字典序解析，比如 20230101_init.sql 和 20230102_add_index.sql 没问题，但 1_init.sql 和 10_add_index.sql 会导致后者先执行。
