golang-migrate在CI中失败主因是环境缺失：数据库服务未启动、连接串硬编码localhost、PG环境变量未注入；需用services启动DB、环境变量拼接DSN、显式传参或export变量、安装二进制。

golang-migrate 命令在 CI 中执行失败的常见原因

CI 环境里 migrate 报错“no such file or directory”或“connection refused”，通常不是代码问题，而是环境缺失。本地能跑不代表 CI 能跑——数据库服务没启动、连接串写死成 localhost:5432、PGUSER/PGPASSWORD 没注入，三者占 90% 的失败场景。

• 确保 CI 步骤中先启动数据库服务（如用 services 在 GitHub Actions 启动 PostgreSQL 容器）
• 连接串必须用环境变量拼接，避免硬编码；推荐格式：postgres://$PGUSER:$PGPASSWORD@postgres:5432/mydb?sslmode=disable
• migrate CLI 默认不读取 .env，得显式传参或在脚本里 export 变量再调用
• 检查 migrate 二进制是否已安装：GitHub Actions 需加一步 curl -L https://github.com/golang-migrate/migrate/releases/download/v4.15.2/migrate.linux-amd64.tar.gz | tar xz 并 chmod +x

如何让 migrate up/down 在不同环境安全执行

开发用 migrate up，上线却不敢直接 down？关键不在命令本身，而在迁移文件设计和执行策略。Golang-migrate 不校验 SQL 语义，删表语句进了 prod 就是事故。

• 禁止在生产环境使用 migrate down；CI 流水线里只允许 up，且仅限 staging 和 prod 分支触发
• 迁移文件名必须带时间戳（如 202405201430_add_users_table.up.sql），避免多人协作时序错乱
• 敏感操作（DROP、ALTER ... RENAME）拆成两步：先加字段+双写，再下线旧逻辑，最后删字段；不要塞进单个 .up.sql
• 用 migrate version 检查目标环境当前版本，再决定是否执行；CI 脚本里加判断：[ "$(migrate version)" = "202405201430" ] || migrate up

Go 项目里嵌入 migrate 的正确姿势

想在 Go 服务启动时自动迁移？别直接调 os/exec.Command("migrate", "up")。CLI 启动慢、错误难捕获、事务不可控——应该用官方 Go SDK。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

• 导入 github.com/golang-migrate/migrate/v4 和对应驱动，如 github.com/golang-migrate/migrate/v4/database/postgres
• 初始化时用 migrate.NewWithDatabaseInstance，传入已建立的 *sql.DB，复用连接池
• 务必设置 migrate.WithStdLogger，否则 panic 不报错；错误要检查 err == migrate.ErrNoChange（已是最新版）而非全当异常
• 不要在 init() 里做迁移；放在 main() 开头或独立 setupDB() 函数里，方便测试 mock

迁移失败后如何快速定位和修复

CI 流水线卡在 migrate 步骤，日志只显示 Error: migration failed: pq: column "xxx" does not exist？这不是 SQL 写错了，是上下游迁移版本没对齐。

立即学习“go语言免费学习笔记（深入）”；

• 立刻查 CI 日志里的完整命令和输出，重点看 migrate status 结果，确认当前 DB 版本和文件系统版本差几级
• 本地复现：用相同 DB 容器、相同迁移文件、相同环境变量跑 migrate -path ./migrations -database "$DSN" status
• 临时修复可手动 migrate force 202405201430（跳过某级），但必须同步更新团队共享的 VERSION 文件或文档
• 长期方案：在 CI 中加前置检查步骤，用 migrate validate 校验 SQL 语法（仅限 PostgreSQL）和文件命名规范

迁移不是“跑完就完”，真正麻烦的是跨环境版本漂移和人肉回滚。每次 merge 迁移文件前，多看一眼 git diff 里有没有 DROP 或重命名操作——这种事没法靠工具兜底。