Django服务React构建文件报404 DEBUG=False时资源加载异常

首先明确报错场景：

Failed to load resource: the server responded with a status of 404 (Not Found) main.7ec538f6.chunk.js:1

Django + React 架构项目，React 构建产物本地直接运行正常，通过Django托管时静态chunk加载失败；DEBUG = False 模式下媒体文件、favicon均返回404无法访问。

1. 修复React chunk文件404问题 #

• 核对Django静态文件核心配置（settings.py）
  确保以下配置项正确：

  import os
  # 静态资源访问URL前缀
  STATIC_URL = '/static/'
  # 执行collectstatic后静态文件的存放目录
  STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
  # 额外要收集的静态文件目录，必须指向React构建产物里的static目录
  STATICFILES_DIRS = [
      os.path.join(BASE_DIR, 'frontend/build/static')
  ]
  

  如果是Create React App搭建的React项目，在项目package.json中新增配置"homepage": "/static/"，保证构建出来的资源引用路径前缀和STATIC_URL一致，避免资源默认从站点根路径加载导致路由不匹配。修改配置后重新执行React构建命令，再在Django项目根目录执行python manage.py collectstatic，把所有静态资源（带哈希的chunk文件）统一收集到STATIC_ROOT目录，不要手动复制构建产物，避免哈希值不匹配或者文件遗漏。
• 调整路由匹配顺序
  注意：静态资源路由必须放在前端兜底路由的前面，否则所有静态资源请求会被React的路由规则拦截，直接返回404。
  参考路由配置：

  from django.views.generic import TemplateView
  from django.conf import settings
  from django.conf.urls.static import static
  from django.urls import path
  
  urlpatterns = [
      # 后端API路由优先放最前面
      # path('api/xxx', your_api_view),
  ]
  
  # 挂载静态、媒体资源路由
  urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
  urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
  
  # 最后挂载React入口的兜底路由
  urlpatterns.append(path('', TemplateView.as_view(template_name='index.html')))
  

  同时确认模板配置正确，settings.py中TEMPLATES的DIRS项要加入React构建产物的根目录，保证Django能找到React的index.html入口：

  TEMPLATES = [
      {
          'BACKEND': 'django.template.backends.django.DjangoTemplates',
          'DIRS': [os.path.join(BASE_DIR, 'frontend/build')], # 指向React build目录
          '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',
              ],
          },
      },
  ]
  

2. 修复DEBUG=False时媒体文件、favicon404问题 #

• Django默认在生产模式（DEBUG=False）下不会自动托管静态和媒体文件，必须显式在路由中追加前面提到的static()路由规则，才能让Django直接返回这些资源。注意：生产环境流量大的场景更推荐用Nginx托管静态/媒体资源，测试环境用上述配置即可正常访问。
• 核对媒体文件配置，settings.py中必须正确配置：

  MEDIA_URL = '/media/'
  MEDIA_ROOT = os.path.join(BASE_DIR, 'media') # 媒体文件实际存放目录
  

  确认Django进程对MEDIA_ROOT、STATIC_ROOT目录有读取权限，Linux环境下如果目录权限配置错误，也会导致资源无法正常返回。
• Favicon修复：把favicon.ico放到React项目的public目录下，构建时会自动打包到build目录，执行collectstatic时会同步收集到静态文件目录；不要在页面中写死/favicon.ico的根路径引用，要使用静态路径规则引用，Django模板中用{% static 'favicon.ico' %}，React项目中直接引用public下的路径即可。

• 直接在浏览器访问报错的chunk文件完整URL，比如http://你的域名/static/js/main.7ec538f6.chunk.js：
  • 如果返回404且路径里没有/static/前缀，是React构建的路径前缀配置错误，回去修改package.json的homepage项重新构建
  • 如果路径正确仍404，去STATIC_ROOT目录下的js文件夹里查找对应哈希名的文件，不存在就是collectstatic执行失败或者STATICFILES_DIRS配置错误
• 查看Django运行时的请求日志，看404请求匹配到的是哪个路由，如果匹配到了前端兜底的index.html路由，就是路由顺序错误，把静态资源路由挪到前面即可。
• 检查文件目录权限，避免Django进程无权限读取文件导致的404。

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