Node.js Express托管create-react-app打包产物静态资源加载报错排查

核心根因 #

• create-react-app的构建产物完全由项目配置生成，所有静态资源的引用路径和package.json的homepage字段直接绑定。手动修改build目录下的文件是无效操作，只要重新执行npm run build，所有修改都会被覆盖，还容易出现路径和实际文件位置不匹配的问题。
• Express服务的静态资源托管写法有误：给静态资源中间件绑定了*通配路径，又让兜底路由拦截了所有请求，导致静态资源请求无法被正确识别，全部被返回index.html内容而非对应静态文件，触发资源解析报错。
• 用serve托管构建产物时，手动修改HTML内的资源路径，会和构建时生成的路径规则冲突，哪怕路径看起来合理，也会因为配置不一致出现404。

分步修复操作 #

• 修改client/package.json中的homepage配置：不要填写带协议、域名的完整地址，直接改成相对路径：

  "homepage": "./"
  

  之前填的http://localhost:5000/属于硬编码部署地址，后续一旦换端口、换域名，就会直接出现资源加载失败；设为./后构建的产物会生成相对路径的资源引用，适配所有同源部署场景。
• 删除旧的build目录，重新执行npm run build生成全新构建产物，过程中不要手动改动build目录里的任何文件。
• 调整Express服务的代码逻辑，修正中间件注册顺序：

  "use strict";
  const express = require('express');
  const app = express();
  const path = require('path');
  
  // 静态资源托管一定要放在所有路由最前面，不要绑定通配符路径
  app.use(express.static(path.join(__dirname, '../client/build/')));
  // SPA路由兜底，匹配所有非静态资源的页面请求
  app.get('/*', (req, res) => {
    res.sendFile(path.resolve(__dirname, '../client/build/index.html'));
  });
  
  app.listen(5000, () => console.log('server listening'));
  

• 用serve工具测试时，直接进入新生成的build目录启动服务即可，不需要手动修改任何HTML内的资源地址：

  cd build
  serve .
  

踩坑提醒

• 静态资源中间件的注册优先级必须高于兜底路由，否则所有请求都会被兜底逻辑拦截，返回HTML内容。
• 不要给express.static()绑定*通配路径，静态资源本身不需要额外的路径前缀，绑定通配符会打乱Express的路径匹配规则。
• 全新create-react-app项目出现的serve托管报错，本质也是构建时默认的homepage路径规则和serve的路径解析逻辑不匹配，改完homepage重新构建就能解决。

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