升级Node至v20.10.0后React项目构建报错postcss-svgo:: Non-whitespace before first tag

问题背景 #

升级Node从v16到v20.10.0并更新npm包后，构建时出现postcss-svgo:: Non-whitespace before first tag错误，报错指向的scss文件内容与实际不符，且未手动安装postcss-svgo，项目使用Craco配置。

解决方案 #

1. 直接禁用css-minimizer中的svgo插件

postcss-svgo是css-minimizer-webpack-plugin默认依赖的子插件，新版本对URL转义的SVG处理更严格。在Craco配置中关闭svgo即可：
在craco.config.js中添加：

module.exports = {
  style: {
    cssMinimizer: {
      pluginOptions: {
        minimizerOptions: {
          preset: [
            'default',
            {
              svgo: false, // 禁用SVG优化，避免转义格式报错
            },
          ],
        },
      },
    },
  },
};

2. 定位并修复问题SVG来源

报错中的SVG是URL转义格式（%3c代替<），可以通过webpack分析工具找到来源：

• 安装依赖：npm install webpack-bundle-analyzer --save-dev
• 在craco.config.js中配置插件：

const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;

module.exports = {
  webpack: {
    plugins: [new BundleAnalyzerPlugin()],
  },
};

• 运行构建命令，打开本地分析页面（默认http://127.0.0.1:8888），找到报错的css chunk，定位到对应的SVG资源：
  • 如果是自己代码中的background-image，将转义的SVG改为正常格式（把%3c替换为<，注意引号转义），或改用base64编码
  • 如果是第三方组件库引入的，尝试回退组件库版本，或提交issue给组件库维护者

3. 锁定postcss-svgo依赖版本

如果是升级后postcss-svgo版本变化导致的兼容性问题，可在package.json中锁定兼容版本：

"overrides": {
  "postcss-svgo": "6.0.0" // 替换为Node v16时能正常工作的版本
}

执行npm install重新安装依赖。

额外排查点 #

• 检查所有scss/css文件中的data:image/svg+xml格式资源，确认是否存在URL转义不规范的SVG
• 确认第三方UI组件库是否在升级后引入了新的SVG资源，导致格式冲突

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