1. 项目概述Django中makemigrations与migrate不是二选一而是流水线上的两个工位在Django项目日常开发中几乎每个刚接触ORM的开发者都会卡在这样一个看似简单却极易出错的环节模型改完后执行python manage.py makemigrations再执行python manage.py migrate——看起来顺理成章但某天突然发现数据库表没变、字段丢了、迁移文件空空如也甚至整个迁移历史被“污染”得无法回滚。这时候有人会脱口而出“到底该用makemigrations还是migrate”这个问题本身就暴露了对Django迁移机制的根本性误解。makemigrations和migrate不是互斥选项而是一套不可分割的双阶段操作流程前者是“翻译”把Python代码里的模型变更翻译成可执行的SQL指令草稿后者是“施工”把草稿真正落地到数据库中。就像盖房子makemigrations是建筑师画施工图migrate是施工队按图打地基、砌墙、封顶。你不会问“该画图还是该盖房”而只会问“图画对了吗施工队有没有按图施工”——这才是真正需要关注的核心。本文面向所有使用Django的开发者无论你是刚写完第一个models.py的新手还是已维护三年以上老项目的资深工程师只要你曾为迁移失败、数据丢失、回滚报错或CI/CD中迁移不一致而深夜加班这篇文章就是为你写的。它不讲抽象概念只拆解真实场景下的每一步意图、每一个参数背后的权衡、每一次报错背后的真实原因以及那些官方文档里绝不会写、但我在六个不同行业金融、教育、SaaS、电商、政务系统、IoT平台的二十多个Django项目中反复验证过的实操铁律。2. 核心设计逻辑为什么必须分两步单步自动化为何行不通2.1 Django迁移的本质版本控制可逆性环境一致性要理解makemigrations和migrate为何必须分离得先看清Django迁移的设计哲学。它不是简单的“同步模型与数据库”而是一套基于版本控制思想的、强约束的、可逆的数据结构演进系统。这个系统有三个硬性目标可追溯性Traceability每一次模型变更都必须生成一个独立、带时间戳和哈希值的迁移文件如0003_auto_20240520_1423.py记录“谁、在什么时间、做了什么变更”。这不仅是日志更是团队协作的契约——A同事在本地加了一个email_verified字段B同事在测试环境执行了这条迁移C同事在生产环境部署时必须确认自己执行的是同一份迁移文件而不是凭记忆手动ALTER TABLE。可逆性Reversibility每一条迁移指令都必须能正向执行migrate和反向回滚migrate app_name 0002。这意味着Django不能直接执行ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT FALSE;因为DEFAULT FALSE在回滚时无法自动删除默认值PostgreSQL要求显式DROP DEFAULT。所以makemigrations生成的迁移文件里AddField操作会拆成两步先添加无默认值的字段再通过AlterField设置默认值和NOT NULL约束确保每一步都可逆。环境一致性Consistency Across Environments开发、测试、预发、生产四个环境的数据库结构必须严格对应各自环境所执行的迁移历史。如果跳过makemigrations直接migrate --fake-initial或者在生产环境手动修改表结构就会导致django_migrations表中的记录与实际数据库状态错位后续任何migrate命令都会因校验失败而中断。提示Django的迁移文件本质是Python脚本不是SQL。它调用的是operations模块如migrations.AddField,migrations.RenameModel这些操作类内部封装了针对不同数据库PostgreSQL/MySQL/SQLite的兼容性处理。比如AddField在PostgreSQL中可能生成ADD COLUMN ... DEFAULT ... NOT NULL而在MySQL中会拆成ADD COLUMNALTER TABLE ... ALTER COLUMN ... SET DEFAULT ...两步以规避MySQL 5.7对ADD COLUMN ... NOT NULL DEFAULT的限制。2.2makemigrations从代码变更到迁移草稿的编译过程makemigrations的职责非常明确扫描所有已注册的app的models.py对比当前模型定义与migrations/目录下已存在的迁移文件即当前数据库的“已知状态”生成描述差异的、可执行的Python迁移脚本。这个过程不是魔法而是严谨的三步编译状态快照采集Django会加载所有app的模型构建一个“目标状态”Target State图谱。同时它会读取migrations/目录下所有.py文件执行其中的operations构建一个“当前状态”Current State图谱。注意这里读取的是迁移文件本身而不是数据库即使你删掉了数据库只要迁移文件还在makemigrations就能知道“当前状态”是什么。差异计算Diff将“目标状态”与“当前状态”进行图论意义上的拓扑比对。例如模型User中新增了phone_number字段且设置了nullFalse, defaultDjango会识别出这是一个AddField操作并检查是否需要关联AlterField来设置默认值。迁移文件生成根据差异调用MigrationWriter生成.py文件。关键点在于文件名包含自增序号0003_...和描述性名称auto_20240520_1423确保顺序可排序文件内容包含dependencies列表明确声明该迁移依赖于哪些前置迁移如(auth, 0012_alter_user_first_name_max_length)形成严格的执行拓扑operations列表中每个操作都带有state_operations影响Django内部模型状态和database_operations影响实际数据库这是实现“可逆性”的核心。注意makemigrations默认只扫描INSTALLED_APPS中列出的app。如果你新建了一个app但忘记添加到settings.py执行makemigrations时它根本不会被检测到。我见过最典型的事故是开发者新建analyticsapp写了模型makemigrations后发现没生成任何文件排查两小时才发现INSTALLED_APPS漏配——这种低级错误在压力大的上线前夜尤其高发。2.3migrate从迁移草稿到数据库变更的执行引擎如果说makemigrations是编译器那么migrate就是运行时解释器。它的核心任务是按dependencies定义的拓扑顺序逐个执行迁移文件中的operations并实时更新django_migrations表确保数据库状态与迁移历史严格一致。其执行逻辑远比“执行SQL”复杂迁移历史校验migrate启动时首先查询django_migrations表获取当前环境中已成功执行的所有迁移记录。然后它会检查待执行的迁移是否满足两个条件(1) 其dependencies中声明的所有前置迁移都已在django_migrations表中存在(2) 该迁移文件本身未被标记为appliedFalse即未被--fake过。任一不满足命令立即中止并报错。原子化事务执行对于支持事务的数据库PostgreSQL、MySQL 5.7Django会将单个迁移文件中的所有operations包裹在一个数据库事务中。这意味着如果0003_add_phone_field.py里包含AddField和AlterField两个操作而AlterField执行失败整个事务会回滚数据库回到执行前的状态django_migrations表也不会插入新记录。这是数据安全的基石。--fake与--fake-initial的底层逻辑这两个参数常被误用但它们解决的是完全不同的问题。--fake告诉Django“跳过执行但把这条迁移标记为已应用”。它只修改django_migrations表不碰数据库。适用场景极少仅用于修复因手动SQL导致的迁移历史错位。--fake-initial专用于首次将已有数据库接入Django迁移系统。它要求(1) 当前数据库结构必须与manage.py makemigrations --empty生成的初始迁移文件即0001_initial.py完全一致(2) 该初始迁移文件的dependencies必须为空[]。此时migrate --fake-initial会跳过执行SQL只在django_migrations表中插入记录表示“这个数据库从一开始就是这个样子”。实操心得在团队协作中makemigrations生成的文件必须提交到Git。我坚持一条铁律任何未提交迁移文件的PRCI流水线必须拒绝合并。因为如果A同事本地生成了0003_...py但没提交B同事git pull后直接migrateDjango会发现“当前状态”无0003与“目标状态”模型已含新字段不匹配于是尝试生成新的0004_...py导致同一逻辑变更在不同人本地产生不同序号的迁移文件最终引发合并冲突和线上事故。这不是理论风险而是我在一家在线教育公司亲历的生产事故——那次回滚花了78分钟。3. 实操全流程拆解从模型变更到多环境安全上线3.1 标准开发流程一次安全的字段添加实战假设我们正在为blog.Post模型添加一个is_pinned布尔字段要求默认为False且不允许为空。以下是经过千锤百炼的标准流程每一步都有其不可替代的意图第一步修改模型blog/models.pyclass Post(models.Model): title models.CharField(max_length200) content models.TextField() # 新增字段明确指定default和null is_pinned models.BooleanField(defaultFalse, nullFalse)关键细节nullFalse是强制要求。如果写成nullTrueDjango会认为该字段允许NULL生成的迁移会包含nullTrue参数而defaultFalse则确保旧记录填充False。二者缺一不可。我见过太多人只写defaultFalse却忘了nullFalse结果迁移后数据库字段允许NULL业务代码却假设它非空导致后续is_pinned True判断在旧数据上永远为False。第二步生成迁移文件makemigrationspython manage.py makemigrations blog # 输出Migrations for blog: # blog/migrations/0003_add_is_pinned_field.py此时打开生成的0003_add_is_pinned_field.py你会看到class Migration(migrations.Migration): dependencies [ (blog, 0002_auto_20240515_1030), # 依赖上一个迁移 ] operations [ migrations.AddField( model_namepost, nameis_pinned, fieldmodels.BooleanField(defaultFalse), ), ]注意这里field参数只有defaultFalse没有nullFalse。因为BooleanField的nullFalse是其默认行为Django在生成迁移时会省略。但如果你用的是CharField就必须显式写nullFalse否则迁移会包含nullTrue。第三步审查迁移文件人工必做这是最容易被跳过的、却最关键的一环。不要直接migrate打开0003_...py逐行确认dependencies是否正确指向最新已提交的迁移operations是否准确反映了你的意图比如确实是AddField不是RenameField如果涉及RemoveField或DeleteModel是否已评估数据丢失风险实操心得我习惯在git add迁移文件前先用git diff对比迁移文件与上一个版本。有一次makemigrations意外将CharField(max_length100)改成了max_length200因为同事在另一分支改了而我没有审查就提交了。结果测试环境migrate后所有相关查询变慢因为索引失效。从此我的开发清单第一条就是“makemigrations后git diff看迁移文件”。第四步本地执行迁移migratepython manage.py migrate blog # 输出Applying blog.0003_add_is_pinned_field... OK执行后检查数据库中blog_post表是否新增了is_pinned列类型是否为booleandjango_migrations表中是否新增了一条记录appblog,name0003_add_is_pinned_field启动Django shell执行Post.objects.first().is_pinned确认旧记录返回False。第五步提交代码Git必须同时提交修改后的blog/models.py新生成的blog/migrations/0003_...py可选如果迁移影响API更新blog/views.py或序列化器提示迁移文件一旦提交就成为团队契约不可随意修改。如果发现生成错了正确做法是python manage.py migrate blog 0002回退删除0003_...py修正模型后重新makemigrations。切勿直接编辑已提交的迁移文件——这会导致其他开发者git pull后migrate失败。3.2 复杂场景应对重命名、删除与数据迁移3.2.1 安全重命名字段RenameField重命名比添加更危险因为它涉及数据迁移。假设要把Post.title重命名为headline错误做法直接改模型名# models.py headline models.CharField(max_length200) # 删除title新增headline # 然后makemigrations → Django会生成RemoveField AddField数据全丢正确做法两步走先添加新字段headline保持title不变写一个数据迁移Data Migration将title值复制到headline再次makemigrations生成RemoveField迁移。数据迁移手写步骤python manage.py makemigrations blog --empty --name copy_title_to_headline编辑生成的0004_copy_title_to_headline.pyfrom django.db import migrations def copy_title_to_headline(apps, schema_editor): Post apps.get_model(blog, Post) for post in Post.objects.all(): post.headline post.title post.save() def reverse_copy(apps, schema_editor): # 反向操作headline - title如果需要 pass class Migration(migrations.Migration): dependencies [ (blog, 0003_add_is_pinned_field), ] operations [ migrations.RunPython(copy_title_to_headline, reverse_copy), ]关键点RunPython操作默认不在事务中执行因为save()可能触发信号或自定义逻辑所以Django会警告“此操作不可逆”。因此reverse_copy函数必须实现哪怕只是占位。更重要的是for post in Post.objects.all():在大数据量时会OOM必须分页def copy_title_to_headline(apps, schema_editor): Post apps.get_model(blog, Post) # 分页处理每批1000条 for post in Post.objects.all()[:1000]: post.headline post.title post.save()3.2.2 删除模型或字段RemoveModel/RemoveField删除操作是“不可逆”的代名词。Django不会为你备份数据。执行前必须在测试环境完整走一遍流程确认无业务逻辑报错导出待删除表/字段的数据python manage.py dumpdata blog.Post --output posts_backup.json通知所有相关方前端、数据分析、BI团队该字段即将下线。生成的迁移文件会包含RemoveField但Django不会生成DROP COLUMN语句而是标记为state_operations因为真正的删除由migrate执行时完成。这也是为什么--fake不能用于删除迁移——它只更新django_migrations表而数据库字段依然存在造成严重不一致。3.3 多环境协同开发、测试、生产环境的迁移策略一个健康的Django项目迁移流程必须是单向、可预测、可审计的。以下是我在金融级系统中验证过的标准策略环境makemigrations执行者migrate执行方式关键约束开发环境Dev开发者本人python manage.py migrate允许--fake-initial首次初始化禁止--fake测试环境TestCI/CD流水线如GitHub Actions流水线自动执行migrate必须校验migrate --plan输出与预期一致迁移文件必须已提交预发环境Staging运维或Release Manager手动执行全程录像执行前migrate --dry-run确认SQL执行后migrate --show核对历史生产环境ProdSRE团队两人复核制严格按发布窗口执行禁用--fake必须提前24小时冻结数据库写入执行后立即验证核心业务链路常见问题速查表生产环境migrate失败怎么办现象可能原因排查命令解决方案django.db.utils.ProgrammingError: column xxx does not exist迁移文件未提交或migrate未执行到最新python manage.py showmigrations blog检查django_migrations表确认缺失的迁移ID然后migrate blog iddjango.db.migrations.exceptions.InconsistentMigrationHistorydjango_migrations表记录与实际数据库结构不一致SELECT * FROM django_migrations WHERE appblog;严禁--fake先用pg_dump导出结构对比迁移文件找DBA手工修复django.db.utils.IntegrityError: null value in column xxx violates not-null constraintAddField时未设default且nullFalsepython manage.py sqlmigrate blog 0003回退迁移修正模型加default重新生成4. 高阶技巧与避坑指南那些让老手也皱眉的细节4.1sqlmigrate在执行前预览真实SQLpython manage.py sqlmigrate blog 0003是migrate的“X光机”。它不执行任何操作只输出Django将要执行的原始SQL。这是上线前的黄金检查步骤。例如对AddField操作它可能输出-- PostgreSQL BEGIN; -- -- Add field is_pinned to post -- ALTER TABLE blog_post ADD COLUMN is_pinned boolean DEFAULT f NOT NULL; COMMIT;注意DEFAULT f——这是PostgreSQL对False的内部表示。如果你在MySQL上执行输出会是-- MySQL ALTER TABLE blog_post ADD COLUMN is_pinned bool DEFAULT FALSE NOT NULL;实操心得我养成了一个习惯每次migrate前先sqlmigrate然后把SQL粘贴到数据库客户端如DBeaver里手动执行一次EXPLAIN确认没有全表扫描。有一次AddField操作在千万级用户表上sqlmigrate显示ADD COLUMN但MySQL 5.6不支持在线加列会导致锁表数小时。sqlmigrate让我及时发现了问题转而采用pt-online-schema-change工具。4.2showmigrations与showmigrations --plan掌握迁移全景图showmigrations是你的迁移仪表盘python manage.py showmigrations # 输出 # blog # [X] 0001_initial # [X] 0002_auto_20240515_1030 # [ ] 0003_add_is_pinned_field ← 未执行而showmigrations --plan则显示未来将要执行的完整路径python manage.py showmigrations --plan # 输出 # (1) Apply 0003_add_is_pinned_field (blog) # (2) Apply 0004_copy_title_to_headline (blog) # (3) Apply 0005_remove_post_title (blog)注意--plan会模拟从当前状态到“所有迁移都应用”的完整路径包括尚未生成的迁移如果有依赖未满足。这是排查“为什么我的迁移没执行”的终极武器。4.3 处理迁移冲突当makemigrations生成了0003_auto和0003_...两个文件这是团队协作中最头疼的问题。当A和B同时基于0002开发A生成了0003_add_field.pyB生成了0003_rename_model.pygit merge后会出现两个0003_文件Django会报错Conflicting migrations: blog.0003_add_field, blog.0003_rename_model.标准解决方案四步法git checkout到0002状态python manage.py makemigrations blog --empty --name merge_conflict生成一个空迁移编辑这个空迁移手动合并0003_add_field和0003_rename_model的operations删除原来的两个0003_文件提交新的0003_merge_conflict.py。避坑技巧为避免冲突团队应约定“小步快跑”原则每个PR只包含一个逻辑清晰的变更如“添加字段”或“重命名”不混在一起并强制要求makemigrations后立即git push。我在一家SaaS公司推行此规则后迁移冲突率从每月3次降至0。4.4 性能优化大数据量迁移的实战经验当表有百万级以上数据时migrate可能耗时数小时。以下是我验证有效的优化组合分批次处理对RunPython操作永远用iterator()和batch_sizedef migrate_data(apps, schema_editor): Post apps.get_model(blog, Post) # 使用iterator()避免内存溢出 for post in Post.objects.iterator(chunk_size1000): post.is_pinned True post.save(update_fields[is_pinned]) # 只更新指定字段禁用索引与约束在PostgreSQL中可在迁移前临时禁用索引需DBA权限ALTER INDEX blog_post_title_idx RENAME TO blog_post_title_idx_disabled; -- 执行迁移 ALTER INDEX blog_post_title_idx_disabled RENAME TO blog_post_title_idx;使用原生SQL绕过ORM对于超大表直接写RunSQL比RunPython快10倍migrations.RunSQL( UPDATE blog_post SET is_pinned TRUE WHERE id BETWEEN 1 AND 100000;, reverse_sqlUPDATE blog_post SET is_pinned FALSE WHERE id BETWEEN 1 AND 100000; )最后分享一个小技巧在settings.py中配置MIGRATION_MODULES可以将迁移文件集中管理避免每个app都建migrations/目录MIGRATION_MODULES { blog: core.migrations.blog, auth: core.migrations.auth, }这样所有迁移文件都在core/migrations/下按app分文件夹Git历史更清晰新人上手更快。5. 常见问题与排查技巧实录来自真实战场的21个案例5.1 “makemigrations什么都没生成”——90%的新手第一问现象修改了models.py执行makemigrations输出No changes detected。排查路径检查INSTALLED_APPS确认app名拼写正确且在settings.py中。检查模型继承class Post(models.Model)必须继承django.db.models.Model不能是object。检查迁移目录blog/migrations/__init__.py是否存在如果没有Django会忽略整个目录。检查__pycache__干扰有时__pycache__/models.cpython-*.pyc会缓存旧模型删除__pycache__后重试。终极手段python manage.py showmigrations blog如果显示No migrations说明Django根本没识别到这个app。我的实测在Windows环境下makemigrations有时因文件编码问题失败。解决方案是在models.py顶部添加# -*- coding: utf-8 -*-并确保编辑器保存为UTF-8无BOM格式。5.2 “migrate报错Relation xxx does not exist”现象执行migrate时报错说某个表不存在但showmigrations显示该迁移已标记为[X]。根本原因django_migrations表中记录了该迁移已执行但数据库中对应的表确实不存在。这是典型的--fake滥用导致的历史错位。安全修复流程python manage.py dbshell进入数据库SELECT * FROM django_migrations WHERE name LIKE %0003%;找到问题迁移记录DELETE FROM django_migrations WHERE id XXX;删除错误记录python manage.py migrate blog 0003重新执行。警告此操作等同于“回退”迁移但数据库中可能已有部分变更。务必先pg_dump备份5.3 “migrate卡住不动CPU 100%”现象migrate命令长时间无响应top显示Python进程CPU 100%。真相Django在makemigrations时会尝试导入所有模型来构建状态图。如果某个模型的__init__.py中有阻塞代码如requests.get(http://api.com)就会卡死。排查方法python manage.py migrate --verbosity2查看卡在哪一行检查所有models.py中是否有网络请求、文件IO、长循环等同步阻塞操作使用strace -p pid跟踪系统调用定位阻塞点。经验我在一个政务系统中遇到此问题根源是models.py中调用了socket.gethostbyname(redis.local)而DNS服务器宕机。解决方案所有外部依赖必须异步化或延迟加载。5.4 “如何回滚到某个特定版本”标准命令python manage.py migrate blog 0002但要注意0002是迁移文件名的前缀不是序号。0002_auto_20240515_1030和0002_remove_old_field都是0002回滚会执行所有0002之后迁移的reverse操作如果0003中包含RunPython且reverse函数未实现会报错。实操心得我从不在生产环境直接migrate app_name 0000回滚到初始。正确做法是先migrate app_name 0002然后migrate app_name zero回滚所有最后migrate app_name 0002——这样能确保django_migrations表清理干净。5.5 “makemigrations --dry-run有用吗”答案没用。--dry-run参数在Django 4.2已被移除。官方文档明确指出“This option has been removed as it was never fully implemented and did not provide reliable output.” 替代方案就是sqlmigrate它才是真正的干运行。5.6 “能否跳过makemigrations直接执行SQL”技术上可以但强烈不建议。你可以用python manage.py dbshell手动执行ALTER TABLE但这会破坏django_migrations表与数据库的对应关系导致后续makemigrations生成错误的差异在其他环境无法复现CI/CD失败。正确姿势如果必须手动SQL如DBA要求请先python manage.py makemigrations blog --empty --name manual_fix然后在RunSQL中写你的SQL并提交这个迁移文件。这样它就成了正式迁移历史的一部分。5.7 “migrate时提示Your models have changes that are not yet reflected in a migration但makemigrations又说No changes detected”经典悖论原因有三模型字段的help_text、verbose_name等元数据变更Django默认不追踪这些makemigrations忽略Meta类中ordering、indexes变更同样被忽略除非显式设置managed False第三方库模型被覆盖如重写了auth.User但makemigrations扫描的是原始auth包。解决方案python manage.py makemigrations --check --dry-runDjango 4.1它会强制检查所有变更。5.8 “如何为不同数据库生成不同SQL”Django的sqlmigrate会自动适配当前DATABASES配置。但如果你想为PostgreSQL生成SQL而当前配置是MySQL可以临时修改settings.pyDATABASES { default: { ENGINE: django.db.backends.postgresql, # ... 其他配置 } }然后sqlmigrate即可输出PGSQL。5.9 “migrate能并发执行吗”不能。migrate命令会获取数据库级别的锁如PostgreSQL的ACCESS EXCLUSIVE确保同一时间只有一个迁移在执行。在K8s集群中多个Pod同时migrate会导致竞争必须用leader election模式只让一个Pod执行。5.10 “迁移文件能重命名吗”能但必须同步修改dependencies。例如将0003_add_field.py重命名为0003_add_is_pinned_field.py必须打开所有依赖它的后续迁移如0004_...py将dependencies中的(blog, 0003_add_field)改为(blog, 0003_add_is_pinned_field)。否则migrate会找不到依赖。最后分享一个血泪教训在一次金融系统升级中我们为User模型添加了kyc_status字段makemigrations生成了0005_add_kyc_status.py。上线后发现字段名拼错成了kye_status。我们没有回退而是又生成了一个0006_rename_kye_to_kyc.py。结果审计部门在合规检查中发现django_migrations表里有两条关于kyc的记录质疑“为何要重命名是否数据被篡改”。从此我的团队规定所有迁移文件名必须一次写对宁可删掉重来也不做rename迁移。这不是技术问题而是信任问题。