Django Rest Framework搭配React时设置debug=False出现空白页问题

核心原因 #

Django 在 debug=False 时关闭了开发环境下的各类自动适配逻辑，包括本地静态资源托管、宽松的域名校验等，白屏问题几乎都和静态资源加载失败或请求被拦截有关，按以下步骤排查即可：

排查解决步骤 #

• 1. 校验 ALLOWED_HOSTS 配置 #

  debug=False 时Django会严格校验请求域名，未在配置列表内的域名会直接返回400错误。在settings.py中确认已添加你实际部署的站点域名：

  ALLOWED_HOSTS = ['你的站点域名', 'www.你的站点域名']
  # 测试阶段可暂时填['*']通配，生产环境建议严格配置
  

  可先打开浏览器控制台看页面请求的状态码，如果是400基本都是这个配置的问题。

• 2. 确认静态资源已同步到S3 #

  debug=False 时Django不会再从本地static目录读取静态资源，所有静态资源（包括React打包后的js、css、图片等）都需要推送到S3存储桶：

  1. 执行 python manage.py collectstatic 命令，把项目所有静态资源归集到统一目录
  2. 确认归集后的资源已经完整上传到S3桶对应的静态资源路径下

• 3. 校验S3相关配置 #

  在settings.py中检查以下配置是否正确：

  # S3桶域名配置，不要写错桶名和区域
  AWS_S3_CUSTOM_DOMAIN = '你的桶名.s3.你的区域.amazonaws.com'
  # 静态资源前缀，要和S3桶内的存放路径匹配
  STATIC_URL = f'https://{AWS_S3_CUSTOM_DOMAIN}/static/'
  # 静态资源存储类配置，确保你已经安装了django-storages依赖
  STATICFILES_STORAGE = 'storages.backends.s3boto3.S3StaticStorage'
  

  另外要检查S3桶的权限配置：

  • 静态资源路径需要开放公共读权限，或者配置了正确的签名访问逻辑
  • CORS规则要允许你的站点域名跨域访问资源，避免跨域拦截导致资源加载失败

• 4. 校验React打包配置 #

  React打包时的PUBLIC_URL配置要和S3的静态资源路径完全匹配，否则打包出来的入口文件内的资源引用路径会出错，导致js、css加载失败白屏：
  如果你是用create-react-app搭建的项目，可以在打包时指定参数：

  PUBLIC_URL=https://你的S3静态资源路径 npm run build
  

  或者在项目的package.json中添加homepage字段配置对应路径。

快速定位方法 #

打开浏览器F12调试工具，切换到「网络」标签后刷新页面：

• 若入口html请求返回400，优先排查ALLOWED_HOSTS
• 若入口html返回200，但后续js/css请求返回404，优先排查路径配置和静态资源上传情况
• 若js/css请求返回403/跨域错误，优先排查S3桶权限和CORS配置

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