Alembic未检测到模型变化是因为target_metadata未正确加载模型；“Table already exists”是因alembic_version表为空导致重复建表；数据变更需手动编写可逆的upgrade/downgrade逻辑；多环境应通过环境变量隔离数据库配置并确保迁移可逆。
alembic revision 生成迁移脚本时没检测到模型变化？
常见现象是运行 alembic revision --autogenerate -m "add user table" 后，生成的脚本里 upgrade 函数为空，或只写了 pass。根本原因不是 Alembic 坏了，而是它默认只对比 env.py 中配置的 target_metadata 和数据库当前状态——而你的模型类（比如 User）没被 target_metadata 加载进去。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 检查
alembic/env.py中是否在run_migrations_online或run_migrations_offline之前，正确导入并赋值了模型的MetaData，例如：target_metadata = Base.metadata（Base是你用declarative_base()创建的） - 确认模型模块在
env.py顶部被 import 过，否则 Python 解释器根本看不到那些类，Alembic 更无从扫描 - 如果用了多个
Base（比如分包定义模型），得手动合并元数据：target_metadata = MetaData()，再逐个调用model1.Base.metadata.reflect(target_metadata)类似操作（不推荐，易错） - 临时验证方式：在
env.py里加一行print([t.name for t in target_metadata.tables.values()])，看输出是否包含你新增的表名
alembic upgrade head 执行报错 “Table already exists”
这是线上环境最常踩的坑：本地开发时用 create_all() 建过表，但 Alembic 的 alembic_version 表还是空的，导致它以为“还没执行过任何迁移”，一跑 upgrade head 就重复建表失败。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 别在已有表的库上直接跑
upgrade；先用alembic stamp head把当前数据库状态“标记”为最新版本（仅写入alembic_version表，不改动结构） - 更安全的做法是：用
alembic history查出所有已生成但未应用的 revision ID，再对每个 ID 手动alembic stamp <id>，确保版本记录和实际结构对齐 - 如果表结构和模型已一致，只是缺记录，也可以进数据库手动插入：
INSERT INTO alembic_version (version_num) VALUES ('xxx...'); - 注意：一旦用
stamp跳过某次迁移，后续就不能再靠downgrade回退那步了——Alembic 不知道那步到底干了什么
迁移脚本里怎么安全处理数据变更（比如改字段类型、拆分列）？
Autogenerate 只能处理纯结构变化（增删表/列），遇到要转换存量数据的操作（如把 full_name 拆成 first_name + last_name），必须手动编辑生成的 revision 文件。这里的关键不是“能不能写 SQL”，而是“怎么让升级和回滚都可逆且不丢数据”。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 避免在
upgrade()里直接ALTER COLUMN ... TYPE，PostgreSQL 等数据库可能因数据不兼容失败；先ADD COLUMN，再用UPDATE填充，最后DROP COLUMN -
downgrade()必须对应：如果upgrade新增了列并迁移了数据，downgrade得把数据合并回原字段，再删新列——不能只写op.drop_column() - 涉及大量数据时，在
upgrade中加注释提醒人工确认，或用op.execute("SELECT count(*) FROM ...")检查数据量，超阈值就抛异常中断 - 测试时务必连真实数据量级的库跑一遍
upgrade→downgrade→upgrade，很多逻辑漏洞只在这时候暴露
不同环境（dev/staging/prod）如何共用一套迁移脚本？
核心矛盾在于：开发时可能频繁修改未提交的 migration 文件，而生产环境要求每次 upgrade 都幂等、可审计。直接共享同一份 alembic.ini 或硬编码数据库 URL 必然出事。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 把
sqlalchemy.url从alembic.ini移到环境变量，env.py中用os.getenv("DATABASE_URL")读取——这样 dev 用 SQLite，prod 用 PostgreSQL，配置完全隔离 - 禁止手动编辑已提交的
.py迁移文件（哪怕只是改个注释）；有调整必须用alembic revision --splice -m "fix typo"新增修正脚本 - CI 流水线里加一步：
alembic upgrade head && alembic downgrade base && alembic upgrade head，验证迁移可逆性 - 生产部署前，先用
alembic upgrade --sql head导出 SQL，给 DBA 审核——有些操作（如长事务锁表）必须提前评估
真正麻烦的从来不是生成脚本，而是当 upgrade 卡在中间、数据库半截状态时，你既不敢硬重启，又没法靠文档还原现场。这时候唯一靠谱的依据，就是每次 revision 里清晰的手动注释和 downgrade 实现。
