如何解决Django中‘BlogProject.urls’的ImproperlyConfigured错误？

错误现象 #

执行crontab定时任务时触发配置错误，日志内容如下：

File "/usr/local/lib/python3.12/site-packages/django/core/checks/urls.py", line 61, in _load_all_namespaces
    url_patterns = getattr(resolver, "url_patterns", [])
File "/usr/local/lib/python3.12/site-packages/django/utils/functional.py", line 47, in __get__
    res = instance.__dict__[self.name] = self.func(instance)
File "/usr/local/lib/python3.12/site-packages/django/urls/resolvers.py", line 748, in url_patterns
    raise ImproperlyConfigured(msg.format(name=self.urlconf_name)) from e
django.core.exceptions.ImproperlyConfigured: The included URLconf 'BlogProject.urls' does not appear to have any patterns in it. If you see the 'urlpatterns' variable with valid patterns in the file then the issue is probably caused by a circular import.

当前配置信息 #

crontab定时任务内容 #

*/1 * * * * /usr/local/bin/python /usr/src/BlogProject/manage.py flushexpiredtokens > /var/log/cron.log 2>&1.

项目根目录urls.py代码 #

from django.urls import path, include
from django.contrib import admin
from django.conf import settings
from django.conf.urls.static import static
from users.views import RegisterView

if settings.DEBUG:
    urlpatterns = [
        path("admin/", admin.site.urls),
        path("", include("users.urls")),
        path("", include("blogger.urls")),
        path("", include("administration.urls")),
    ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

settings.py关键配置片段 #

from celery.schedules import crontab
import os
from pathlib import Path
from datetime import timedelta

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = ""

DEBUG = bool(os.environ.get("DEBUG", default=0))

ALLOWED_HOSTS = ['example.com', 'localhost', '127.0.0.1']

AUTH_USER_MODEL = "users.User"

INSTALLED_APPS = [
    # Installed apps...
    'django_crontab',  # Django Crontab
]

MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

问题原因及修复方案 #

核心原因 #

1. URL模式仅在DEBUG环境定义：settings.py中DEBUG默认取环境变量值，默认是0（关闭状态），而urls.py仅在DEBUG=True时才定义urlpatterns，导致crontab执行（默认非DEBUG环境）时无可用URL模式，触发配置错误。
2. crontab环境变量缺失：系统级crontab执行时不会自动加载项目的环境变量，可能导致配置读取异常。

修复步骤 #

1. 修正urls.py，确保所有环境都有URL模式
   将基础URL模式移出if settings.DEBUG判断，仅在DEBUG环境添加静态文件服务（生产环境建议用Nginx等服务处理静态资源）：

   from django.urls import path, include
   from django.contrib import admin
   from django.conf import settings
   from django.conf.urls.static import static
   from users.views import RegisterView
   
   # 所有环境生效的基础URL模式
   urlpatterns = [
       path("admin/", admin.site.urls),
       path("", include("users.urls")),
       path("", include("blogger.urls")),
       path("", include("administration.urls")),
   ]
   
   # DEBUG环境额外添加media文件服务
   if settings.DEBUG:
       urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
   

2. 修复crontab的环境变量问题

   • 方案一：直接在crontab中指定必要环境变量（生产环境不建议开启DEBUG，优先用步骤1的修复）：

     */1 * * * * DEBUG=0 /usr/local/bin/python /usr/src/BlogProject/manage.py flushexpiredtokens > /var/log/cron.log 2>&1
     

   • 方案二：通过shell脚本加载环境后执行命令：
     创建/usr/src/BlogProject/run_flushtokens.sh：

     #!/bin/bash
     cd /usr/src/BlogProject
     # 加载项目所需环境变量，例如虚拟环境、数据库配置等
     export PYTHONPATH=/usr/src/BlogProject
     /usr/local/bin/python manage.py flushexpiredtokens
     

     赋予执行权限：chmod +x /usr/src/BlogProject/run_flushtokens.sh
     修改crontab：

     */1 * * * * /usr/src/BlogProject/run_flushtokens.sh > /var/log/cron.log 2>&1
     

3. 排查循环导入（可选）
   如果完成上述修复后仍报错，检查各app的urls.py、views.py是否存在循环导入（如A模块导入B，B模块又导入A）。

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