Django执行migrate或runserver前会隐式调用系统检查框架,检测模型与数据库结构不一致、配置缺失、字段约束冲突等问题,发现严重错误(如模型变更但无迁移文件)时抛出SystemCheckError并中止执行。

因为 Django 的模型定义和数据库实际结构可能不一致,不检查就直接运行 migrate 或 runserver,轻则报错中断,重则 silently 破坏数据一致性。
model 修改后没跑 makemigrations 就直接 migrate
这是最常见触发检查的场景。Django 在执行 migrate 前会隐式调用系统检查框架,发现模型字段新增但无对应迁移文件时,会抛出 SystemCheckError 并阻止迁移继续。
- 错误信息通常是:
django.core.management.base.SystemCheckError: System check identified some issues:+ 具体字段名和应用名 - 本质是 Django 检测到“模型有变更,但迁移历史缺失”,属于严重错误(
Error级别),无法绕过 - 解决方式只能是先补上
python manage.py makemigrations app_name,再migrate
settings.py 中 DATABASES 配置缺失或别名拼写错误
当项目配置了多数据库,但某处代码硬编码使用了未在 DATABASES 字典中声明的数据库别名(比如写了 using='user_db',但 settings 里只有 'users'),系统检查会在 runserver 启动时立即报错。
- 典型错误:
django.utils.connection.ConnectionDoesNotExist: The connection user_db doesn't exist - 这个检查发生在 Django 初始化阶段,早于任何请求处理,所以服务根本起不来
- 注意:空的
'default': {}是合法的,但所有后续操作必须显式指定--database=xxx,否则检查失败
字段约束冲突导致迁移无法生成 SQL
比如给一个已存在大量数据的表添加非空(null=False)字段,且没提供 default 或 blank=True,makemigrations 本身不会报错,但后续 sqlmigrate 或 migrate 会触发检查并失败。
立即学习“Python免费学习笔记(深入)”;
- PostgreSQL 下可能报:
NOT NULL constraint cannot be added to column without default value - MySQL 下更隐蔽:迁移命令能跑完,但实际执行 SQL 时卡住或锁表,检查框架会在
sqlmigrate阶段尝试预估 SQL 时提前预警 - 真正安全的做法是:先加
null=True字段,再用RunPython迁移填充数据,最后alter_field改为非空
自定义检查被忽略但实际影响部署
很多团队把检查警告(Warning)用 SILENCED_SYSTEM_CHECKS 屏蔽了,比如忽略 models.W042(外键没设 on_delete),上线后遇到级联删除逻辑失控。
- 这类警告不会阻断命令,但一旦发生数据误删或查询 N+1,debug 成本远高于提前修复
- 建议只屏蔽明确知晓后果且接受风险的项,例如测试环境的
security.W004(DEBUG=True) - 生产部署前务必运行
python manage.py check --deploy,它会启用额外的严格检查项
真正容易被忽略的是:检查框架默认不校验数据库连接是否可达,只校验配置语法和模型逻辑。如果数据库服务宕机或网络不通,check 命令照样通过,直到第一个查询才暴露问题——这时候得靠 CONN_HEALTH_CHECKS = True 和合理的 CONN_MAX_AGE 配合兜底。


















