React应用部署至Vercel后持续出现空白页面求助

问题详情 #

部署React应用到Vercel时，已将平台Node版本调整为和本地一致，部署流程成功完成，但访问部署链接时，页面仅加载一秒就变为空白。已尝试以下操作均未解决：

• 移除Strict Mode
• 修改package.json中的homepage为"."
• 将BrowserRouter替换为HashRouter

相关部署域名：

• moviehub-ten.vercel.app
• moviehub-git-main-kingmathers92.vercel.app
• moviehub-auo3bth4l-kingmathers92.vercel.app

我的package.json内容：

{
  "name": "movie-hub",
  "version": "0.1.0",
  "private": true,
  "homepage": "https://moviehub-ten.vercel.app",
  "dependencies": {
    "@alan-ai/alan-sdk-web": "^1.8.43",
    "@emotion/react": "^11.10.6",
    "@emotion/styled": "^11.10.6",
    "@mui/icons-material": "^5.11.11",
    "@mui/material": "^5.11.12",
    "@mui/styles": "^5.11.12",
    "@reduxjs/toolkit": "^1.9.3",
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "axios": "^1.3.4",
    "react": "^18.2.0",
    "react-circular-progressbar": "^2.1.0",
    "react-dom": "^18.2.0",
    "react-redux": "^8.0.5",
    "react-router-dom": "^6.8.2",
    "react-scripts": "5.0.1",
    "web-vitals": "^2.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "eslint": "^8.17.0",
    "eslint-config-airbnb": "^19.0.4",
    "eslint-plugin-import": "^2.26.0",
    "eslint-plugin-jsx-a11y": "^6.5.1",
    "eslint-plugin-react": "^7.30.0",
    "eslint-plugin-react-hooks": "^4.5.0"
  }
}

排查与解决步骤 #

1. 查看浏览器控制台错误 #

空白页90%以上是运行时错误导致的，按F12打开开发者工具，切换到Console面板，查看是否有报错信息，比如：

• API请求失败（密钥未配置、跨域问题）
• Redux状态初始化异常
• 第三方库兼容性报错
• 路由匹配失败

2. 修正homepage配置 #

当前package.json中homepage写死了固定域名，会导致其他部署域名的资源路径错误。建议改为：

"homepage": ".",

或者直接删除该字段——Vercel部署Create React App应用时，默认会自动处理资源路径，无需手动配置。

3. 配置Vercel环境变量 #

如果应用依赖API密钥（比如电影数据接口的key），本地的.env文件不会上传到Vercel，必须在Vercel项目的Settings > Environment Variables中手动配置对应的环境变量，确保生产环境能正常读取。

4. 本地验证生产构建 #

在本地执行npm run build生成生产包，然后全局安装serve工具：

npm install -g serve

接着启动本地服务：

serve -s build

访问http://localhost:3000，如果本地也出现空白页，说明问题出在代码本身，和Vercel部署无关，可针对性排查代码逻辑。

5. 修复React Router路由配置 #

如果使用BrowserRouter，Vercel需要配置路由重写规则，避免刷新页面时出现404或空白。在项目根目录创建vercel.json文件，内容如下：

{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}

同时检查React Router v6的路由配置，确保所有路由都被<Routes>包裹，且配置了兜底路由：

<Routes>
  <Route path="/" element={<Home />} />
  {/* 其他路由 */}
  <Route path="*" element={<NotFound />} />
</Routes>

6. 排查依赖兼容性 #

检查package.json中的依赖版本，比如react-scripts 5.0.1和React 18.2.0兼容，但部分第三方库可能存在生产环境适配问题。可以尝试更新相关依赖，或者临时移除非核心库（比如Alan AI SDK），验证是否是该库导致的问题。

内容的提问来源于stack exchange，提问作者Khaled Ben yahya