部署在S3+CloudFront的React SPA刷新/直链访问白屏问题求助

1. 静态资源路径配置错误 #

这是最常见的诱因：React打包时的公共路径配置不匹配部署环境，导致JS、CSS等核心资源加载失败，页面无内容渲染。

• 排查：打开浏览器控制台的Network标签，刷新页面，查看静态资源的请求状态，若显示404，说明路径配置错误。
• 解决：
  • 若使用Create React App：在package.json中设置"homepage"字段，根路径部署设为"/"，子路径（如https://xxx.com/my-app/）部署则设为"/my-app/"。
  • 若使用Vite：在vite.config.js中配置base: "/my-app/"（对应实际部署路径）。
  • 重新打包后上传至S3，确保资源引用路径与部署环境一致。

2. CloudFront缓存未刷新 #

修改配置后，CloudFront可能仍缓存着旧页面或资源，导致新配置无法生效。

• 解决：
  • 登录CloudFront控制台，找到目标分发，进入缓存→缓存失效，输入路径"/*"，创建失效请求，强制刷新所有缓存内容。
  • 同时确认S3桶内的index.html为最新打包版本，无旧文件遗留。

3. React Router路由配置问题 #

使用BrowserRouter时，路由的basename或匹配规则错误会导致页面无法正常渲染。

• 排查：查看控制台的Console标签，是否存在路由相关报错信息。
• 解决：
  • 若部署在子路径下，给BrowserRouter添加basename属性：<BrowserRouter basename="/my-app">。
  • 确保路由配置包含兜底规则，避免未匹配的路由触发白屏：

    <Route path="*" element={<NotFoundPage />} />
    

4. CloudFront自定义错误页面配置有误 #

错误页面路径或状态码映射配置错误，导致返回的index.html不符合预期。

• 解决：
  • 检查CloudFront分发的自定义错误响应：
    • 错误代码选择404，自定义响应页面路径填/index.html（必须带开头的斜杠）。
    • HTTP状态码选择200 OK，缓存最小TTL可设为0（避免缓存错误页面）。
  • 确认S3桶中index.html存在且权限正确（CloudFront可正常读取）。

5. 权限或CORS问题 #

静态资源被浏览器拦截无法加载，导致页面白屏。

• 排查：控制台Network标签中资源请求状态为403，或Console出现CORS报错。
• 解决：
  • 配置S3桶的CORS规则，允许CloudFront域名访问（调试阶段可临时设为*）：

    <CORSConfiguration>
      <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
        <AllowedHeader>*</AllowedHeader>
      </CORSRule>
    </CORSConfiguration>
    

  • 确认CloudFront的Origin Access Control（OAC）配置正确，确保CloudFront有权限读取S3桶内容，而非直接公开S3桶权限。

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