升级rehype-katex后React项目可构建但yarn start启动失败如何解决

AI 小北

2026-10-7

报错根因

报错是因为rehype-katex@6.x的依赖包hast-util-to-text使用了ES2021新增的数字分隔符语法（即报错代码中0x20_0b里的下划线），你当前使用的react-scripts@4.0.3内置的babel版本不支持解析该语法，且开发环境默认只转译src目录下的代码，不会处理node_modules下的依赖语法，因此启动时抛出解析错误。
生产构建正常是因为react-scripts4的生产构建配置会对公共依赖做兼容性转译，codesandbox环境默认使用更高版本的构建工具，原生支持该语法。

解决方案

以下方案按优先级从高到低排列，任选其一即可：

方案1：升级react-scripts到5.x（最推荐）

高版本的react-scripts内置的babel已经原生支持数字分隔符语法，无需额外配置，直接执行升级命令即可：

yarn add react-scripts@5

升级完成后重新执行yarn start就能正常启动。如果升级后出现其他依赖兼容性问题，再更换其他方案即可。

方案2：不升级react-scripts，修改构建配置

如果暂时不想升级react-scripts，可以通过react-app-rewired覆盖默认构建规则，添加对应语法的转译支持：

安装所需开发依赖：

yarn add -D react-app-rewired customize-cra @babel/plugin-proposal-numeric-separator

在项目根目录新建config-overrides.js文件，写入以下内容：

const { override, addExternalBabelPlugin } = require('customize-cra');

module.exports = override(
  addExternalBabelPlugin('@babel/plugin-proposal-numeric-separator')
);

修改package.json中的scripts配置，把执行命令替换为react-app-rewired：

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build",
  "start": "react-app-rewired start",
  "build": "react-app-rewired build",
  "test": "react-app-rewired test",
  "eject": "react-scripts eject"
}

修改完成后重新执行yarn start即可。