Django-React集成故障：页面空白或提示Template does not exist错误

问题概述 #

集成Django与React时，页面要么加载空白，要么抛出「Template does not exist」错误。直接在urls.py中指定index.html时会显示空白页，已尝试修改文件路径、确认CSS MIME类型，问题仍未解决。

当前配置代码 #

settings.py 模板配置段 #

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [os.path.join(BASE_DIR, 'backend', 'dist')],
        '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_URL = '/static/'

STATICFILES_DIRS = [
    os.path.join(BASE_DIR, 'backend', 'dist', 'static', 'assets'),
]

# 注意：此处存在重复配置，需删除下方重复代码
# STATIC_URL = '/static/'
# STATICFILES_DIRS = [
#     os.path.join(BASE_DIR, 'backend', 'dist', 'static', 'assets'),
# ]

urls.py 路由配置 #

from django.contrib import admin
from django.urls import path, include, re_path
from django.views.generic import TemplateView


urlpatterns = [
    path('admin/', admin.site.urls),
    path('auth/', include('djoser.urls')),
    path('auth/', include('djoser.urls.jwt')),    
]

urlpatterns += [re_path(r'^.*', TemplateView.as_view(template_name='index.html'))]

index.html 内容 #

<!doctype html>
<html lang="en">
  <head>
      <meta charset="UTF-8" />
      <link rel="icon" type="image/png+xml" href="Logo.png" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <link rel="preconnect" href="https://fonts.googleapis.com">
      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
      <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono&display=swap" rel="stylesheet">

    <script type="module" crossorigin src="/assets/index-fhkDj9Lf.js"></script>
    <link rel="stylesheet" crossorigin href="/assets/index-TTwl8E9H.css">
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

解决方案步骤 #

1. 验证模板路径正确性

   • 在settings.py中添加print(BASE_DIR)，运行项目后查看控制台输出的实际路径，确认BASE_DIR/backend/dist目录下确实存在index.html文件。
   • 若路径不符，调整TEMPLATES中的DIRS配置，比如如果dist目录在项目根目录而非backend下，改为os.path.join(BASE_DIR, 'dist')。

2. 清理重复的静态配置

   • 删除静态文件配置中重复的STATIC_URL和STATICFILES_DIRS代码，避免配置冲突。

3. 修正静态资源引用路径

   • React打包后的资源路径为/assets/xxx，但Django的静态文件前缀是/static/，且STATICFILES_DIRS指向backend/dist/static/assets，因此需要修改React打包配置：
     • 若使用Vite，在vite.config.js中设置base: '/static/'，重新打包后资源路径会变为/static/assets/xxx，与Django配置匹配。
     • 若使用Create React App，在package.json中添加"homepage": "/static/"，重新打包。
   • 或者直接修改index.html中的资源路径，将/assets/改为/static/assets/。

4. 确保静态文件服务正常

   • 确认INSTALLED_APPS中包含django.contrib.staticfiles。
   • 开发环境下DEBUG=True时，Django会自动从STATICFILES_DIRS加载静态文件；生产环境需运行python manage.py collectstatic将静态文件收集到STATIC_ROOT指定目录。

5. 排查空白页原因

   • 打开浏览器开发者工具（F12），查看控制台是否有资源加载错误（404），确认静态文件是否能正常访问。
   • 检查React是否正确挂载到#root节点，可在index.js中添加控制台日志验证是否执行。

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