Django DRF遇ImproperlyConfigured错误，排查循环导入无果求助

我在使用Django REST Framework (DRF) 时遇到了错误：django.core.exceptions.ImproperlyConfigured: The included URLconf，检查了years应用的urls.py配置没发现问题，排查循环导入也没找到异常，希望能帮忙定位问题。

项目里的years应用用DRF构建API，Year模型仅存储四位年份（如2020、2021），User应用会导入该模型让用户选择birth_year，另外vehicles应用的VehicleYear模型也关联了Year模型。

相关代码展示 #

years应用 #

urls.py

from rest_framework.routers import DefaultRouter
from .views import YearModelViewSet

app_name = 'years'

router = DefaultRouter()
router.register('calendar-years', YearModelViewSet, basename='calendar-year')

urlpatterns = router.urls

views.py

from rest_framework.permissions import IsAdminUser
from rest_framework.viewsets import ModelViewSet

from .models import Year
from .serializers import YearSerializer

from .permissions import IsAdminOrReadOnly


class YearModelViewSet(ModelViewSet):
    permission_classes = [IsAdminUser | IsAdminOrReadOnly]
    queryset = Year.objects.all()
    serializer_class = YearSerializer
    lookup_field = 'year'

serializers.py

from rest_framework import serializers

from .models import Year

class YearSerializer(serializers.ModelSerializer):
    class Meta:
        model = Year
        fields = ['dev_year_id', 'year', 'slug']

Year模型代码

class Year(models.Model):
    dev_year_id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False) # sqlite
    year = models.SmallIntegerField(unique=True, validators=[
                            MinLengthValidator(4), MaxLengthValidator(4)])
    slug = models.SlugField(unique=True, validators=[
                            MinLengthValidator(4), MaxLengthValidator(4)])
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    def __str__(self):
        return self.year

    class Meta:
        db_table = 'year'
        ordering = ['-year']
        verbose_name = _('Year')
        verbose_name_plural = _('Years')

vehicles应用 #

models.py 片段

from years.models import Year

class VehicleYear(models.Model):
    model_year = models.OneToOneField(Year, ...)

另外Vehicle模型中有一个名为year的外键，不确定是否会引发命名混淆：

class Vehicle(models.Model):
  dev_vehicle_id = models.UUIDField(...)
  year = models.ForeignKey(VehicleYear, ...)  # 这行是否会引发错误？

完整报错栈 #

Traceback (most recent call last):
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/urls/resolvers.py", line 720, in url_patterns
    iter(patterns)
TypeError: 'module' object is not iterable

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/xxx/projects/yyyy/zzzzz/backend/manage.py", line 22, in <module>
    main()
  File "/home/xxx/projects/yyyy/zzzzz/backend/manage.py", line 18, in main
    execute_from_command_line(sys.argv)
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/management/__init__.py", line 442, in execute_from_command_line
    utility.execute()
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/management/__init__.py", line 436, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/management/base.py", line 416, in run_from_argv
    self.execute(*args, **cmd_options)
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/management/base.py", line 457, in execute
    self.check(**check_kwargs)
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/management/base.py", line 492, in check
    all_issues = checks.run_checks(
                 ^^^^^^^^^^^^^^^^^^
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/checks/registry.py", line 89, in run_checks
    new_errors = check(app_configs=app_configs, databases=databases)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/checks/urls.py", line 44, in check_url_namespaces_unique
    all_namespaces = _load_all_namespaces(resolver)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/checks/urls.py", line 74, in _load_all_namespaces
    namespaces.extend(_load_all_namespaces(pattern, current))
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/core/checks/urls.py", line 63, in _load_all_namespaces
    url_patterns = getattr(resolver, "url_patterns", [])
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/utils/functional.py", line 47, in __get__
    res = instance.__dict__[self.name] = self.func(instance)
                                         ^^^^^^^^^^^^^^^^^^^
  File "/home/xxx/projects/yyyy/zzzzz/backend/venv/lib/python3.12/site-packages/django/urls/resolvers.py", line 728, in url_patterns
    raise ImproperlyConfigured(msg.format(name=self.urlconf_name)) from e
django.core.exceptions.ImproperlyConfigured: The included URLconf '<module 'years' from '/home/xxx/projects/yyyy/zzzzz/backend/years/__init__.py'>' 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. 根urls.py配置错误（最可能原因） #

报错栈里明确提到URLconf指向的是years模块的__init__.py，而不是years.urls，说明你在项目根urls.py里的include路径写错了。

错误写法：

path('api/years/', include('years')),

正确写法：

path('api/years/', include('years.urls')),

2. 循环导入验证 #

如果确认根urls.py配置正确，尝试用延迟加载queryset的方式排查循环导入问题：

class YearModelViewSet(ModelViewSet):
    permission_classes = [IsAdminUser | IsAdminOrReadOnly]
    serializer_class = YearSerializer
    lookup_field = 'year'

    def get_queryset(self):
        # 延迟加载queryset，避免初始化时的循环导入
        return Year.objects.all()

3. Year模型的__str__方法错误 #

Year模型的__str__返回的是整数类型的self.year，Django要求该方法必须返回字符串，会引发类型错误，修改为：

def __str__(self):
    return str(self.year)

4. 模型关联的疑问解答 #

• VehicleYear的OneToOneField：如果一个Year对应多个VehicleYear，应该用ForeignKey而不是OneToOneField，一对一关联意味着每个Year只能绑定一个VehicleYear，根据你的业务需求调整即可。
• Vehicle模型的year字段命名：不会直接引发错误，但容易和Year模型的year字段混淆，建议改成vehicle_year这类更清晰的名称，提升代码可读性。

5. 基础配置检查 #

确保years应用已经添加到settings.py的INSTALLED_APPS列表中：

INSTALLED_APPS = [
    # ... 其他应用
    'years',
    'rest_framework',
]

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