bigywater.tech
Django · 26

Django 系统检查框架

每次 runserver 或 migrate 前面那句 “System check identified no issues” 是什么?你能往里加自己的检查吗?Error 和 Warning 差在哪?这篇写三个自定义检查,在真实项目里把它们的作用范围逐个验证。

Error 拦下
自定义 Error 让 check / migrate / makemigrations / test / runserver 都无法执行
Warning 不拦
check 仍然 rc=0;--fail-level WARNING 才让它失败
6 个
check --deploy 对开发向设置报出的警告数

无问题与自定义 Error

实测 · 本机执行输出
  rc=0  System check identified no issues (0 silenced).
实测 · 本机执行输出
  check → rc=1
    SystemCheckError: System check identified some issues:
    
    ERRORS:
    ?: (lab.E001) 自定义检查:发现一个错误
    	HINT: 把它修好
    
    System check identified 1 issue (0 silenced).
  migrate → rc=1  最后一行: 	HINT: 把它修好
  runserver → rc=1  最后一行: System check identified 1 issue (0 silenced).

用 @register(Tags.models) 装饰一个返回 Error 列表的函数即可加入检查;检查在 AppConfig.ready() 里导入(这样才会注册)。

Warning、标签与静音

实测 · 本机执行输出
  check → rc=0
    System check identified some issues:
    
    WARNINGS:
    ?: (lab.W001) 自定义检查:这只是个警告
    
    System check identified 1 issue (0 silenced).
  check --fail-level WARNING → rc=1
  check --tag lab_tag → rc=0
  check --tag models(不含 lab_tag) → rc=0  System check identified no issues (0 silenced).
实测 · 本机执行输出
  SILENCED_SYSTEM_CHECKS=[lab.W001] → rc=0 System check identified no issues (1 silenced).

标签(Tags.models 或自定义字符串)决定 --tag 能选到它。已知且接受的警告用 SILENCED_SYSTEM_CHECKS 静音。

--deploy

实测 · 本机执行输出
  rc=0;报出的检查 id: ['security.W001', 'security.W002', 'security.W003', 'security.W009', 'security.W012', 'security.W018']
  最后一行: System check identified 6 issues (0 silenced).

register(..., deploy=True) 的检查只在 --deploy 时运行。上线前把它加进 CI。

哪些命令会检查

实测 · 本机执行输出
  manage.py check                              LAB_ERR=1 时 rc=1  被检查拦下
  manage.py migrate --check                    LAB_ERR=1 时 rc=1  被检查拦下
  manage.py showmigrations                     LAB_ERR=1 时 rc=1  被检查拦下
  manage.py makemigrations --check --dry-run   LAB_ERR=1 时 rc=1  被检查拦下
  manage.py test --noinput                     LAB_ERR=1 时 rc=1  被检查拦下
  manage.py help                               LAB_ERR=1 时 rc=0  没有被拦
  manage.py shell -c pass                      LAB_ERR=1 时 rc=0  没有被拦

需要数据库或依赖完整配置的命令会先检查;help、shell -c 不会。

分步演示:检查框架

系统检查框架
本步的对象

    本文用到的工具与边界

    • 本机 macOS 27 / Python 3.14.7 / Django 6.1.1(默认用 SQLite,其它数据库会在文中注明),用 django.test.Client 或真实的本机服务器进程实测;计时用 time.perf_counter,数字每次运行会有小幅抖动。自定义检查靠环境变量 LAB_ERR / LAB_WARN 开关
    • 没有验证:数据库相关检查(Tags.database)在 migrate 之外何时运行、check 对多数据库的 --database 选项、Django 自带检查的完整清单、fail-level 取 ERROR / CRITICAL 时的差别
    京ICP备2026067502号-1京公网安备11010502063487号