通过GitHub Actions部署React到Vercel出现304状态码空白页问题

结合你描述的构建日志警告、本地正常但CI部署异常的情况，按以下顺序排查修复：

1. 修复环境变量加载失败问题 #

构建日志里的Failed to load ./.env.是核心隐患——本地能正常加载.env但CI环境中缺失，会导致React应用依赖的环境变量未注入，运行时出错引发空白页，304状态码可能只是缓存掩盖了真实错误。

• 检查Vercel项目的预览环境变量配置：确保本地.env里的所有变量都已在Vercel控制台「Settings → Environment Variables」中添加，且关联到preview环境。
• 调整Workflow中的vercel pull命令，添加--scope参数指定组织，避免拉取环境信息失败：

  vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }} --scope=${{ secrets.VERCEL_ORG_ID }}
  

• 或者跳过vercel pull，直接在Workflow中注入环境变量：在env块中添加需要的变量，示例：

  env:
    VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
    VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
    REACT_APP_API_URL: ${{ secrets.REACT_APP_API_URL }} # 替换为你的实际变量
  

2. 强制刷新Vercel缓存，解决304问题 #

304状态码表示浏览器复用了未修改的旧缓存，但新部署的资源可能因构建异常不完整，导致缓存的旧资源无法正常渲染。

• 在部署命令中添加--force参数，强制跳过缓存验证：

  vercel deploy --prebuilt --force --token=${{ secrets.VERCEL_TOKEN }}
  

• 部署完成后，手动按Ctrl+Shift+R（Windows）或Cmd+Shift+R（Mac）强制刷新浏览器，清除本地缓存。

3. 处理构建文件超标的警告 #

虽然构建成功，但文件体积超标可能导致Vercel资源分发异常，间接引发空白页：

• 确保React生产构建优化生效：若使用Create React App，package.json中的build命令应为react-scripts build，该命令默认会压缩代码、移除冗余内容。
• 清理冗余依赖：用npm ls检查并卸载未使用的包，减少构建产物体积。
• 配置Vercel资源优化：在Vercel控制台开启「Settings → Framework Presets」自动优化，或在项目根目录添加vercel.json配置：

  {
    "builds": [
      {
        "src": "package.json",
        "use": "@vercel/static-build",
        "config": {
          "distDir": "build"
        }
      }
    ],
    "routes": [
      {
        "src": "/(.*)",
        "dest": "/index.html"
      }
    ]
  }
  

4. 验证构建产物完整性 #

在Workflow中添加步骤，检查构建后的build目录内容，确保关键文件存在且正常：

- name: Check Build Artifacts
  run: |
    ls -la build/
    cat build/index.html | grep -E "(static|REACT_APP_)" # 验证静态资源路径和环境变量是否注入

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