Django加载ReactJS生产构建静态资源404、页面空白求助

故障场景描述 #

• 技术栈组合：ReactJS + Django + REST API
• 正常运行状态：单独执行npm start启动React开发服务、单独执行python manage.py runserver启动Django服务时，前后端功能均可正常运行
• 故障现象：尝试通过Django直接渲染React项目build目录下的index.html时，明明对应静态文件实际存在，请求却返回404，最终页面渲染空白并抛出资源加载错误

参考材料：项目目录结构说明、运行终端日志截图

现有配置参考 #

settings.py 核心配置片段 #

import os
from pathlib import Path

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

ALLOWED_HOSTS = [
    "127.0.0.1"
]


INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'corsheaders',
    'rest_framework.authtoken',
    'rest_auth',
    'polluser.apps.PolluserConfig',
    'restapi.apps.RestapiConfig',
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'rest_auth.registration',
]

SITE_ID = 1 

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
    'corsheaders.middleware.CorsMiddleware',
]

ROOT_URLCONF = 'template.urls'

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

WSGI_APPLICATION = 'template.wsgi.application'

# ... 密码校验、国际化配置省略 ...

STATIC_URL = '/static/'
STATICFILES_DIR = [
    os.path.join(BASE_DIR, 'static')
]
STATIC_ROOT = os.path.join(BASE_DIR, 'static')

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

CORS_ORIGIN_ALLOW_ALL = True

ACCOUNT_EMAIL_VERIFICATION = "none"
ACCOUNT_AUTHENTICATION_METHOD = "username"
ACCOUNT_EMAIL_REQUIRED = False

urls.py 路由配置 #

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

urlpatterns = [
    path('', TemplateView.as_view(template_name="build/index.html")),
    path('admin/', admin.site.urls),
    path('api/', include('restapi.urls')),
    path('rest-auth/', include('rest_auth.urls')),
    path('rest-auth/registration/', include('rest_auth.registration.urls')),
]

核心问题定位（从现有配置直接识别的错误） #

• 模板搜索路径缺失：当前TEMPLATES配置的DIRS列表仅包含BASE_DIR/static目录，但路由中指定加载的模板是build/index.html，build目录根本不在Django的模板搜索路径内，导致模板本身就无法被正确读取
• 静态配置变量名错误：静态文件搜索路径的配置变量名写为STATICFILES_DIR，但Django官方定义的有效配置为STATICFILES_DIRS（复数，末尾带s），拼写错误会导致整段配置完全不生效，Django无法识别自定义静态资源目录
• 静态路径逻辑冲突：当前将STATIC_ROOT（生产环境静态文件收集目录）和开发环境静态资源搜索目录设为同一个BASE_DIR/static路径，会导致资源加载逻辑混乱，后续执行collectstatic时还会出现目录嵌套、循环收集的问题
• 前端资源路径不匹配：React构建产物默认以根路径为前缀加载静态资源，若Django的静态资源服务路径、目录配置不匹配build产物的实际文件结构，就会出现“文件实际存在但返回404”的现象

分步解决方案 #

1. 修正模板搜索路径配置
   打开settings.py中的TEMPLATES配置，将React build目录的绝对路径添加到DIRS列表中，保证Django能找到build下的index.html：

   TEMPLATES = [
       {
           # ... 其他配置保持不变
           'DIRS': [
               os.path.join(BASE_DIR, 'static'),
               # 新增这一行，指向React的build目录
               os.path.join(BASE_DIR, 'build'),
           ],
           # ... 其他配置保持不变
       },
   ]
   

   对应路由的模板名修改为index.html即可（因为已经把build目录加到模板搜索路径了，不需要再写build前缀，否则会出现多层路径匹配错误）。

2. 修正静态文件配置的拼写错误
   将原来拼写错误的STATICFILES_DIR改为正确的STATICFILES_DIRS，同时拆分STATIC_ROOT路径，避免逻辑冲突：

   STATIC_URL = '/static/'
   # 修正拼写：把STATICFILES_DIR改成STATICFILES_DIRS
   STATICFILES_DIRS = [
       # 这里指向React build目录下的static子目录，也就是React构建产物里存js/css的路径
       os.path.join(BASE_DIR, 'build', 'static')
   ]
   # 调整STATIC_ROOT为独立的生产收集目录，不要和开发目录混用
   STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
   

3. 调整前端构建的公共路径
   在React项目的根目录创建.env文件，设置PUBLIC_URL=/static/，保证React构建产物生成的静态资源引用路径和Django的STATIC_URL完全匹配，避免路径不对应导致的404。

4. 校验路由顺序
   保持现有urls.py中前端模板路由的位置在所有API、admin路由之后，避免非页面请求被前端路由拦截，在开发环境下可以优先测试接口请求是否正常响应，再测试前端页面渲染。

验证方法 #

• 修改完配置后重启Django服务，访问首页查看是否能正常加载index.html
• 打开浏览器开发者工具的网络面板，检查所有js、css静态资源的请求状态，确认返回200而非404
• 执行python manage.py findstatic命令，传入任意一个React构建的静态文件名，验证Django是否能正确定位到文件路径

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