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 -
migrateCLI 默认不读取.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。
- 导入
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 或重命名操作——这种事没法靠工具兜底。
