GORM的AutoMigrate仅支持新增表、字段和索引，不支持删列、改类型、重命名或回滚，上线后结构变更易静默失败；生产环境应选用golang-migrate/migrate CLI管理版本化SQL迁移。
为什么 GORM 的 AutoMigrate 不够用
GORM 的 AutoMigrate 适合开发初期快速建表，但它本质是“补全式迁移”：只加字段、建索引、新增表，不删字段、不改类型、不重命名列（v2 虽支持部分重命名，但依赖数据库约束且不可逆）。一旦上线后需要调整结构，比如把 user_name 改成 username，或把 VARCHAR(50) 扩到 VARCHAR(100)，AutoMigrate 就会静默忽略或报错。
常见错误现象包括：
- 执行
DB.AutoMigrate(&User{})后，字段名没变，旧列还在，新列又多一个 - 修改 struct tag 中的
column名称，但数据库表毫无反应 - 删除 struct 字段后，对应数据库列仍存在，且
AutoMigrate不会清理
选 golang-migrate/migrate 还是 gormigrate
golang-migrate/migrate 是事实标准，CLI 工具成熟、驱动丰富（MySQL/PostgreSQL/SQLite）、支持 up/down 双向操作、可版本回滚；gormigrate 是基于 GORM 的封装，写法更 Go 风格，但底层仍调用 SQL，且对复杂变更（如数据迁移）支持弱、文档少、社区更新慢。
推荐直接用原生 golang-migrate/migrate，理由很实际：
- 迁移文件是纯 SQL 或 Go 函数，可控性强，便于 DBA 审核
- CLI 命令统一：
migrate -path ./migrations -database "mysql://..." -verbose up - 支持环境变量注入 DSN，方便 CI/CD 中切换测试/生产库
- down 操作能精准撤销上一次 migration，避免手动写 rollback SQL
如何让 migrate 和 Gin 启动流程自然衔接
不要在 main() 里硬编码调用 migrate.Up() —— 它可能失败（比如锁表、权限不足），而你希望服务启动失败时明确报错，而不是静默跳过。
正确做法是把迁移作为启动前检查步骤：
- 在
cmd/main.go中，初始化 DB 连接后、注册路由前，调用migrate.Exec或 CLI 封装函数 - 使用
migrate.New构造实例时，传入io.Discard替代默认 logger，避免日志污染 - 捕获
migrate.ErrDirty：表示 migration history 表有未完成的记录，需人工介入（不能自动修复） - 建议加个开关参数，例如
--migrate-only，方便运维单独执行迁移而不启 HTTP 服务
示例关键片段：
driver, err := mysql.WithInstance(db.DB, &mysql.Config{})
if err != nil {
log.Fatal("failed to create migrate driver:", err)
}
m, err := migrate.NewWithDatabaseInstance(
"file://migrations",
"mysql",
driver,
)
if err != nil {
log.Fatal("failed to instantiate migrate:", err)
}
if err := m.Up(); err != nil && !errors.Is(err, migrate.ErrNoChange) {
log.Fatal("migration failed:", err)
}
MySQL 下迁移文件命名与路径的坑
migrate 对文件名格式极其敏感：必须是 数字_描述.up.sql 和 数字_描述.down.sql 成对出现，且数字递增。Gin 项目中常犯的错是：
- 用中文或空格命名，比如
001_添加用户表.up.sql→ CLI 解析失败 - 把
.up.sql文件放错目录，比如混在models/下 →-path参数找不到 - MySQL 驱动默认不支持
utf8mb4的注释，导致含 emoji 的 SQL 报错ERROR 1064 - 忘记在 DSN 中加
parseTime=true&loc=Local，导致时间字段解析异常影响 migration 执行
安全做法：
- 用
date +%s生成时间戳命名，如1723495620_add_users_table.up.sql - 迁移目录固定为
migrations/，并 git 提交（别忽略它） - 所有 SQL 文件开头加
SET NAMES utf8mb4; - 本地开发用 Docker 启 MySQL 时，确认
character-set-server=utf8mb4已生效
真正麻烦的从来不是写第一条 migration，而是第 17 次上线前发现 down 脚本漏写了数据补偿逻辑——这类问题不会报错，只会悄悄破坏一致性。
