基于路由的React应用本地构建运行正常，部署至Netlify/Vercel后显示空白页问题咨询

我碰到过好多次这种本地正常、部署后掉链子的情况，核心原因基本都绕不开单页应用(SPA)的路由机制和平台的默认配置差异，具体来说有这几个常见坑：

1. 前端路由模式与服务器重定向不匹配 #

React Router默认使用browserHistory模式（不带#的干净路由），这种模式下，本地用serve启动时，serve会自动把所有路由请求转发到index.html；但Netlify/Vercel这类平台默认不会这么做——当用户直接访问/about这类子路由时，服务器会去寻找对应的物理文件，找不到就返回空白（或404）。

解决办法： #

• 临时方案：切换到Hash模式：修改路由配置，用HashRouter代替BrowserRouter，路由会变成/#/about这种格式，服务器只会处理根路径的index.html，路由完全由前端处理。
• 推荐方案：配置平台重定向规则：
  • Netlify：在项目根目录创建_netlify.toml文件，添加以下内容：

    [[redirects]]
      from = "/*"
      to = "/index.html"
      status = 200
    

  • Vercel：在项目根目录创建vercel.json文件，添加以下内容：

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

  这两种配置都会让服务器把所有路由请求转发到index.html，交给前端路由处理。

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

如果package.json里的homepage字段配置不对，会导致CSS、JS等静态资源加载失败，页面自然空白。比如本地开发时不需要这个配置，但部署到线上时，平台需要知道资源的根路径。

解决办法： #

在package.json中添加或修改homepage字段：

• 如果是部署到平台的默认域名（比如your-app.netlify.app），直接设为相对路径：

  "homepage": ".",
  

• 如果是自定义域名，设为你的域名：

  "homepage": "https://your-custom-domain.com",
  

3. 环境变量未正确配置 #

如果你的应用依赖环境变量（比如API地址、密钥），本地开发时可能在.env文件里配置了，但部署到Netlify/Vercel时没有同步设置，会导致组件渲染失败，出现空白页。

解决办法： #

• Netlify：在后台项目设置的「环境变量」里添加对应的变量（比如REACT_APP_API_URL）；
• Vercel：在后台项目的「Settings」→「Environment Variables」中添加变量。
  注意：React环境变量必须以REACT_APP_开头才能被识别。

4. 构建命令或目录配置错误 #

有时候平台的构建命令或产物目录和你的项目不匹配，导致部署的不是最新的构建产物，自然显示空白。

解决办法： #

• Netlify：在项目设置的「Build & Deploy」→「Build settings」里，确认构建命令是npm run build，发布目录是build（如果你的项目构建后产物在dist文件夹，就改成dist）；
• Vercel：默认会自动识别React项目的构建命令和目录，如果有问题，可以在vercel.json里指定：

  {
    "buildCommand": "npm run build",
    "outputDirectory": "build"
  }
  

先从路由重定向和homepage配置查起，这两个是最常见的原因，一般解决后就能正常显示了。

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