Heroku部署集成json-server、express.js的React应用空白页排查

核心问题定位 #

单独部署json-server时运行正常，集成Express后出现根路径返回{}的空白页，本质是路由匹配顺序错误/静态资源配置失效，请求没有落到React的入口文件，反而被接口路由/默认响应拦截返回了空对象。

按优先级排查修复 #

• 调整server.js路由匹配顺序
  Express的路由是严格按照代码书写顺序从上到下匹配的，只要前面的路由命中就不会往后走。出现这个问题基本都是把json-server路由、测试用的返回{}的接口写在了最前面，导致根路径请求直接被拦截返回。

  正确顺序铁则：先挂载带统一前缀的API路由，再配置静态资源托管，最后写单页应用的路由兜底规则，顺序错了100%出问题。

• 给json-server加独立API前缀，不要挂载在根路径
  直接把json-server挂在/根路径会和前端路由完全冲突，必须给所有接口加统一前缀（比如/api），参考配置：

  const jsonServer = require('json-server');
  const apiRouter = jsonServer.router('db.json'); // 替换成你的db.json实际路径
  const jsonMiddlewares = jsonServer.defaults();
  // 所有接口统一走/api前缀，修改后原/users接口变为/api/users，记得同步修改前端的请求地址
  app.use('/api', jsonMiddlewares, apiRouter);
  

• 修正静态资源托管路径
  集成Express后需要手动托管React打包生成的静态文件，路径要写绝对路径，避免Heroku环境下相对路径识别错误，参考配置：

  const path = require('path');
  // 如果你的React项目在根目录的client文件夹下就用这个路径，根据实际项目结构调整即可
  app.use(express.static(path.join(__dirname, 'client', 'build')));
  

• 补全单页应用路由兜底规则
  React是单页应用，所有前端路由都需要重定向到入口index.html，否则Express找不到对应路径就会走到其他路由返回异常，这段代码必须放在所有路由的最末尾：

  app.get('*', (req, res) => {
    res.sendFile(path.join(__dirname, 'client', 'build', 'index.html'));
  });
  

• 修正Heroku环境专属配置
  • 不要写死监听端口：Heroku会动态分配端口，必须读取环境变量，参考写法：

    const PORT = process.env.PORT || 5000;
    app.listen(PORT);
    

  • 补全自动构建脚本：在服务端根目录的package.json里添加heroku-postbuild命令，保证部署时自动安装前端依赖、打包前端文件，否则Heroku上不会生成build文件夹，自然找不到静态资源：

    "scripts": {
      "start": "node server.js",
      "heroku-postbuild": "cd client && npm install && npm run build"
    }
    

本地验证流程 #

改完配置不要直接推Heroku，本地先验证：

1. 进入前端目录执行npm run build生成打包文件
2. 回到服务端目录执行npm start启动服务
3. 访问本地5000端口，确认前端页面正常渲染，访问/api/users确认接口返回正常
   本地验证通过后再推送代码到Heroku部署，问题即可解决。

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