拆分Django的urls.py为多文件时出现URL配置错误，求助排查

问题场景 #

我用基于函数的视图拆分Django应用的URL配置，项目结构如下：

my_project/
  |- my_project/
    |- urls.py
  |- my_app/
    |- urls
      |- __init__.py
      |- dogs.py
      |- cats.py
    |- views
      |- __init__.py
      |- dogs
        |- index.py
...

相关配置代码如下：

my_project/my_app/urls/__init__.py #

from .dogs import urlpatterns as dog_urls
from .cats import urlpatterns as cat_urls

app_name = "pets"

urlpatterns = dog_urls + cat_urls

my_project/my_app/urls/dogs.py #

from .. import views

urlpatterns = [
  path("dogs/", views.dogs.index, name="dogs")
  ...
]

my_project/my_project/urls.py #

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

from . import views

urlpatterns = [
  path("pets/", include("pets.urls")),
  ...
]

if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

配置完成后触发错误：

django.core.exceptions.ImproperlyConfigured: The included URLconf '<module 'pets.urls' (namespace)>' 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.

问题排查与修复 #

1. 根URL配置的路径错误 #

根urls.py里的include("pets.urls")是错误的——pets是你设置的app_name，而include需要引用实际的应用模块路径，你的应用是my_app，所以应该改成include("my_app.urls")。Django找不到pets.urls这个模块，自然加载不出有效URL规则。

修改后根urls.py的对应部分：

urlpatterns = [
  path("pets/", include("my_app.urls")),
  ...
]

2. 视图导入与语法错误 #

dogs.py里存在两个问题：

• 视图导入路径：from .. import views 导入的是my_app.views，但views.dogs.index的写法需要确保my_app/views/dogs/__init__.py正确导出了index视图，或者直接导入具体视图文件。
• 语法错误：path行末尾缺少逗号，会导致Python解析失败，urlpatterns无法正常初始化。

修正后的dogs.py示例：

# 直接导入具体视图函数
from ..views.dogs.index import index

urlpatterns = [
  path("dogs/", index, name="dogs"),  # 补上末尾的逗号
  # 其他URL规则...
]

如果在my_app/views/dogs/__init__.py中已经导出了视图：

# my_app/views/dogs/__init__.py
from .index import index

也可以这样导入：

from ..views.dogs import index

urlpatterns = [
  path("dogs/", index, name="dogs"),
  ...
]

3. 检查cats.py的配置 #

确保cats.py的结构和dogs.py完全一致，没有语法错误，且正确定义了urlpatterns。如果cats.py的urlpatterns为空或者加载失败，dog_urls + cat_urls也会导致最终的urlpatterns无效。

验证 #

修改完成后，删除项目中的__pycache__目录清除缓存，重新启动Django开发服务器，测试URL是否正常访问。

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