react-scripts与最新稳定版@ckeditor5依赖兼容问题求助

问题概述 #

使用react-scripts + craco集成CKEditor的项目，近期依赖更新后出现两类构建错误：

1. 生产构建失败：执行npm run build（或直接react-scripts build）时触发Cannot read properties of undefined (reading 'includes')，定位到MiniCssExtractPlugin模块
2. 开发服务启动失败：执行craco start时触发TypeError: Cannot read properties of undefined (reading 'createSnapshot')，错误源于html-webpack-plugin

降级@ckeditor/ckeditor5-dev-utils至29.0.2版本可临时解决问题，但长期依赖旧版本并非最优方案。

核心原因分析 #

问题本质是**@ckeditor/ckeditor5-dev-utils 30.x版本与react-scripts内置的Webpack生态插件存在版本兼容性冲突**：

• @ckeditor/ckeditor5-dev-utils 30.x版本引入了对Webpack相关插件（如MiniCssExtractPlugin、html-webpack-plugin）的新API依赖，但react-scripts（尤其是v5版本）内置的插件版本较低，不支持这些新API
• 此前能正常使用30+版本，大概率是当时依赖树中插件版本刚好处于兼容区间，后续其他依赖的更新打破了这个平衡，触发了隐藏的版本冲突

排查方向 #

1. 梳理依赖版本树 #

• 执行以下命令，查看关键依赖的实际安装版本：

  npm ls webpack mini-css-extract-plugin html-webpack-plugin @ckeditor/ckeditor5-dev-utils
  

  对比@ckeditor/ckeditor5-dev-utils 30.x的官方文档要求，确认react-scripts提供的插件版本是否满足其API要求。
• 使用npm why <package-name>命令，排查是否有其他依赖（如CKEditor其他包、craco插件）强制升级了Webpack相关插件，导致版本不匹配：

  npm why mini-css-extract-plugin
  npm why html-webpack-plugin
  

2. 核对CKEditor官方变更记录 #

• 查看@ckeditor/ckeditor5-dev-utils的CHANGELOG，确认30.x版本中涉及Webpack插件的API变更点，比如是否调用了MiniCssExtractPlugin或html-webpack-plugin的新方法，而react-scripts内置版本未实现这些方法。
• 确认react-scripts版本与CKEditor开发工具包的兼容范围，比如react-scripts v5对应的@ckeditor/ckeditor5-dev-utils最高兼容版本。

3. 强制兼容版本测试 #

• 在package.json中添加overrides字段（npm 8.3+支持），强制指定Webpack相关插件为react-scripts兼容的版本，再测试30.x版本的@ckeditor/ckeditor5-dev-utils是否能正常工作：

  "overrides": {
    "mini-css-extract-plugin": "5.0.0",
    "html-webpack-plugin": "5.5.0"
  }
  

  注：版本号需替换为react-scripts内置的对应版本，可通过npm ls mini-css-extract-plugin查看。

长期解决方案 #

1. 升级react-scripts到最新版本：新版本通常会同步更新内置的Webpack及插件版本，可能直接解决与@ckeditor/ckeditor5-dev-utils 30.x的兼容性问题。
2. 锁定兼容版本组合：若暂时无法升级react-scripts，可在package.json中明确锁定@ckeditor/ckeditor5-dev-utils到29.0.2，并添加注释说明冲突原因，待后续react-scripts更新后再尝试升级。
3. 检查Craco自定义配置：若craco.config.js中有手动修改MiniCssExtractPlugin或html-webpack-plugin的配置，尝试移除自定义配置后重新测试，排除配置冲突的可能性。

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