升级Node.js 20后Docusaurus构建因CSS Minimizer插件失败

问题背景 #

将Docusaurus文档站（Algo）升级至v3.5.2、切换到Node.js 20后，执行npm run build时客户端打包阶段会在CSS压缩环节崩溃，报错Call retries were exceeded。原因是项目依赖的旧版styled-components@^4.4.1与Node.js 20兼容性不佳，但升级styled-components到最新版时，又因react-simple-chatbot@0.5.3锁定了styled-components@^4.0.0的peer依赖导致安装冲突。

可行解决方案 #

方案一：强制覆盖peer依赖（npm/yarn/pnpm均支持） #

利用包管理器的依赖覆盖功能，让react-simple-chatbot使用新版styled-components，绕过peer依赖检查：

1. 在package.json中添加overrides字段（npm 8.3+支持）：

{
  "overrides": {
    "react-simple-chatbot": {
      "styled-components": "^6.4.2"
    }
  }
}

2. 重新安装依赖：

npm install

3. 测试组件功能：由于强制覆盖可能存在潜在兼容性问题，启动开发服务器验证聊天机器人组件是否正常运行：

npm run start

方案二：调整CSS压缩器配置，绕过旧依赖的崩溃问题 #

不升级styled-components，而是修改Docusaurus的webpack配置，调整CSS minimizer的参数或替换压缩器，避免重试次数超限：

1. 在docusaurus.config.js中添加自定义webpack配置：

module.exports = {
  // ...其他配置
  webpack: {
    configure: (config) => {
      // 找到CSS minimizer插件
      const cssMinimizerIndex = config.optimization.minimizer.findIndex(
        minimizer => minimizer.constructor.name === 'CssMinimizerPlugin'
      );
      if (cssMinimizerIndex !== -1) {
        // 修改插件配置，增加重试次数或调整压缩选项
        config.optimization.minimizer[cssMinimizerIndex] = new config.optimization.minimizer[cssMinimizerIndex].constructor({
          minimizerOptions: {
            preset: [
              'default',
              {
                discardComments: { removeAll: true },
                // 禁用可能导致崩溃的压缩选项
                mergeRules: false,
              },
            ],
            parallel: 4,
            minify: (data, inputMap) => {
              try {
                return require('cssnano').process(data, {
                  ...inputMap,
                  preset: ['default', { mergeRules: false }]
                });
              } catch (e) {
                // 捕获错误，避免构建崩溃
                console.warn('CSS压缩出错，跳过当前文件:', e.message);
                return { css: data };
              }
            }
          },
        });
      }
      return config;
    },
  },
};

2. 重新执行构建：

npm run build

方案三：fork组件仓库并更新peer依赖 #

如果上述方案都无法解决，可自行forkreact-simple-chatbot仓库，更新其peer依赖范围：

1. 克隆自己的fork仓库，修改package.json中的peerDependencies：

{
  "peerDependencies": {
    "styled-components": "^4.0.0 || ^5.0.0 || ^6.0.0"
  }
}

2. 将修改后的仓库用git地址直接安装：

npm install git+https://github.com/your-username/react-simple-chatbot.git

3. 升级styled-components到最新版：

npm install styled-components@latest

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