Django加载静态main.css时触发最大递归深度错误问题排查

问题背景 #

• 项目初始阶段将登录、注册页面全部放在单一dbManagementApp应用内时运行无异常
• 新增独立accounts应用存放登录注册逻辑、将各应用模板拆分到对应专属目录后，页面渲染触发报错

报错信息 #

模板渲染阶段抛出递归超限错误：

In template ###, error at line 7

maximum recursion depth exceeded while calling a Python object
1   <!DOCTYPE html>
2   <html lang="en" dir="ltr">
3       <head>
4           <meta charset="utf-8">
5           <title>HOME</title>
6           {% load static %} <!-- load the static folder for css-->
7           <link rel="stylesheet" href="{% static 'main.css' %}">

异常栈关键报错信息：

File "C:\Users\lukep\anaconda3\envs\djangoenv\lib\site-packages\django\template\base.py", line 766, in __init__
    self.literal = float(var)
ValueError: could not convert string to float: "'main.css'"

问题相关配置 #

• 项目主urls.py配置

from django.contrib import admin
from django.urls import path, include
from dbManagementApp import dbmviews
from accounts import accviews

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('dbManagementApp.dbmurls')),
    path('accounts/', include('accounts.accurls'))
]

• dbManagementApp/dbmurls.py路由配置

from django.urls import path
from . import dbmviews
from django.conf import settings
from django.conf.urls.static import static


urlpatterns = [
    path('', dbmviews.home, name='home'),
    path('aboutus/', dbmviews.aboutUs, name='aboutUs'),
    path('pricing/', dbmviews.pricing, name='pricing'),
    path('contact/', dbmviews.contact, name='contact'),
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

• dbManagementApp/dbmviews.py视图代码

from django.shortcuts import render, redirect
from django.views import View
from .models import Doc
from .forms import DocumentForm
from django.contrib import messages
from django.http import HttpResponse
from django.http import JsonResponse

def home(request):
    return render(request, 'dbmapp/index.html')

• templates/dbmapp/index.html模板代码

<html lang="en" dir="ltr">
    <head>
        <meta charset="utf-8">
        <title>HOME</title>
        {% load static %} <!-- load the static folder for css-->
        <link rel="stylesheet" href="{% static 'main.css' %}">

• accounts/accurls.py路由配置

from django.urls import path
from . import accviews

urlpatterns = [
    path('register/', accviews.register, name='register'),
    path('login/', accviews.login, name='login')
]

• accounts/accviews.py视图代码

from django.shortcuts import render, redirect
from django.contrib.auth.forms import UserCreationForm

def register(request):
    if request.method == "POST":
        form = UserCreationForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect('login')
    else:
        form = UserCreationForm()
    return render(request, 'registration/register.html', {'form':form})

def login(request):
    return render(request, 'registration/login.html')

根因说明 #

报错核心是Django模板引擎解析{% static 'main.css' %}标签时，没有正确调用内置static标签逻辑，进入无限递归流程最终触发深度超限，中途误将字符串参数当做数值解析，抛出字符串转浮点数失败的附带异常。高频触发原因如下：

• 新增应用后自定义模板标签覆盖了Django内置的static标签，自定义标签逻辑存在递归渲染问题
• 模板代码复制时带入零宽空格、全角符号等不可见非法字符，导致模板引擎无法识别static标签语法，误将标签内容当做数值表达式解析
• 静态路由配置在子应用路由文件中，路由匹配顺序异常导致静态文件请求被业务视图拦截，返回的HTML页面再次引用同路径css触发请求递归
• settings中静态文件、模板配置错误，比如未启用django.contrib.staticfiles、STATIC_ROOT指向模板目录、模板查找路径配置错误

修复步骤 #

1. 排查标签命名冲突
   遍历所有应用下的templatetags目录，删除命名为static.py的自定义标签文件，重命名所有自定义的名为static的标签函数，避免覆盖Django内置标签。
2. 修复模板语法问题
   手动删除模板中{% load static %}和{% static 'main.css' %}两行代码，重新手动输入（不要复制粘贴），确保所有符号都是半角英文；将标签行尾部的HTML注释单独成行，或改用Django原生注释{# 加载静态文件目录 #}，避免解析异常。
3. 修正settings配置
   • 确认INSTALLED_APPS中已添加django.contrib.staticfiles
   • 确认模板配置符合规范：

   TEMPLATES = [
       {
           'BACKEND': 'django.template.backends.django.DjangoTemplates',
           'DIRS': [BASE_DIR / 'templates'],
           'APP_DIRS': True,
           'OPTIONS': {
               'context_processors': [
                   'django.template.context_processors.debug',
                   'django.template.context_processors.request',
                   'django.contrib.auth.context_processors.auth',
                   'django.contrib.messages.context_processors.messages',
               ],
           },
       },
   ]
   

   • 确认静态文件配置正确，部署用的STATIC_ROOT不能和静态源文件目录、模板目录重合：

   STATIC_URL = 'static/'
   STATICFILES_DIRS = [BASE_DIR / 'static']
   STATIC_ROOT = BASE_DIR / 'static_collect'
   

4. 修正路由配置
   将静态文件、媒体文件服务路由从子应用dbmurls.py中移除，统一放到项目主urls.py的最末尾，避免路由匹配顺序错误。修正后主urls.py代码如下：

   from django.contrib import admin
   from django.urls import path, include
   from django.conf import settings
   from django.conf.urls.static import static
   from dbManagementApp import dbmviews
   from accounts import accviews
   
   urlpatterns = [
       path('admin/', admin.site.urls),
       path('', include('dbManagementApp.dbmurls')),
       path('accounts/', include('accounts.accurls'))
   ] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
   

   修正后dbManagementApp/dbmurls.py只保留业务路由：

   from django.urls import path
   from . import dbmviews
   
   urlpatterns = [
       path('', dbmviews.home, name='home'),
       path('aboutus/', dbmviews.aboutUs, name='aboutUs'),
       path('pricing/', dbmviews.pricing, name='pricing'),
       path('contact/', dbmviews.contact, name='contact'),
   ]
   

5. 校验静态文件存放路径
   公共main.css文件放在项目根目录的static文件夹下，应用专属静态文件放在对应应用的static目录下，引用时添加应用前缀避免重名冲突，比如{% static 'dbmapp/main.css' %}。

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