将Django从3.2 LTS升级到5.0.4出现requires_system_checks类型错误

问题 #

将Django从3.2 LTS版本升级至最新的5.0.4版本，并按需更新了所有依赖包，但在执行docker-compose启动API服务器时出现以下报错：

my-api            |   File "/opt/my-api-core/manage.py", line 22, in <module>
my-api            |     execute_from_command_line(sys.argv)
my-api            |   File "/usr/local/lib/python3.10/site-packages/django/core/management/__init__.py", line 442, in execute_from_command_line
my-api            |     utility.execute()
my-api            |   File "/usr/local/lib/python3.10/site-packages/django/core/management/__init__.py", line 436, in execute
my-api            |     self.fetch_command(subcommand).run_from_argv(self.argv)
my-api            |   File "/usr/local/lib/python3.10/site-packages/django/core/management/__init__.py", line 275, in fetch_command
my-api            |     klass = load_command_class(app_name, subcommand)
my-api            |   File "/usr/local/lib/python3.10/site-packages/django/core/management/__init__.py", line 49, in load_command_class
my-api            |     return module.Command()
my-api            |   File "/usr/local/lib/python3.10/site-packages/django_media_fixtures/management/commands/collectmedia.py", line 35, in __init__
my-api            |     super(Command, self).__init__(*args, **kwargs)
my-api            |   File "/usr/local/lib/python3.10/site-packages/django/core/management/base.py", line 285, in __init__
my-api            |     raise TypeError("requires_system_checks must be a list or tuple.")
my-api            | TypeError: requires_system_checks must be a list or tuple.

已尝试以下操作但未解决：

• 将依赖从django-media-fixtures替换为django-media-fixtures-next
• 将Django从5.0.4降级至4.2.11甚至4.1版本

不想直接修改site-packages目录，寻求合理解决方案。

解决方案 #

1. 更换为兼容的替代包 #

放弃django-media-fixtures系列包，改用维护活跃、支持Django 4.x/5.x的替代包，比如django-fixture-media或django-media，这些包针对新版Django做了兼容性适配，不会出现requires_system_checks类型错误。

2. 自定义collectmedia命令替代 #

在项目中创建自定义命令，绕过第三方包的问题：

1. 在项目任意已注册的app下创建路径management/commands/collectmedia.py
2. 写入以下代码（可根据实际需求调整媒体文件复制逻辑）：

from django.core.management.base import BaseCommand
from django.conf import settings
import shutil
import os

class Command(BaseCommand):
    requires_system_checks = []  # 符合Django新版要求的空列表

    def handle(self, *args, **options):
        # 定义媒体fixture源目录和目标目录
        source_dir = os.path.join(settings.BASE_DIR, 'fixtures', 'media')
        target_dir = settings.MEDIA_ROOT

        # 确保目标目录存在
        os.makedirs(target_dir, exist_ok=True)

        # 递归复制媒体文件
        for root, _, files in os.walk(source_dir):
            for file in files:
                src_path = os.path.join(root, file)
                # 获取相对路径，保持目录结构
                rel_path = os.path.relpath(src_path, source_dir)
                dest_path = os.path.join(target_dir, rel_path)
                # 创建目标子目录
                os.makedirs(os.path.dirname(dest_path), exist_ok=True)
                # 复制文件（保留元数据）
                shutil.copy2(src_path, dest_path)

        self.stdout.write(self.style.SUCCESS('媒体fixture文件已成功收集'))

3. 确保该app在settings.py的INSTALLED_APPS中，启动时即可使用自定义命令替代第三方包的命令。

3. 临时跳过该命令（若非必需） #

检查docker-compose启动脚本是否调用了collectmedia命令，如果该命令不是服务器启动的必需步骤，可暂时移除该命令，先启动服务器，后续再单独处理媒体fixture的收集问题。

内容的提问来源于stack exchange，提问作者Ananth