React项目升级Ag-Grid至v28后，新CSS导入路径引发构建报错

核心问题分析 #

你遇到的ParserError大概率是因为Create React App（CRA）默认的Webpack loader配置没有正确匹配ag-grid-community/styles/路径下的CSS文件，导致编译时无法解析该文件的语法。React 16.13.1本身与Ag-Grid v28是兼容的（v28要求React 16.8+），模块导入CSS的方式也符合CRA的规范，所以核心还是Webpack loader的匹配问题。

无需Eject的解决方法：使用react-app-rewired修改配置 #

CRA不允许直接修改Webpack配置，但可以通过react-app-rewired + customize-cra工具链在不eject的情况下调整配置，具体步骤如下：

1. 安装依赖
   在项目根目录执行：

   npm install react-app-rewired customize-cra --save-dev
   

2. 修改package.json的脚本命令
   将原有的start、build、test命令替换为：

   "scripts": {
     "start": "react-app-rewired start",
     "build": "react-app-rewired build",
     "test": "react-app-rewired test",
     "eject": "react-scripts eject"
   }
   

3. 创建配置文件config-overrides.js
   在项目根目录新建该文件，添加以下内容，确保Webpack的CSS loader能正确处理ag-grid-community/styles下的文件：

   const { override, adjustStyleLoaders } = require('customize-cra');
   
   module.exports = override(
     adjustStyleLoaders(({ use: [, css, postcss, resolve, processor] }) => {
       // 排除ag-grid的CSS文件，不启用CSS Modules
       css.options.modules = {
         auto: (resourcePath) => !resourcePath.includes('ag-grid-community/styles'),
       };
     })
   );
   

   如果报错是因为CSS语法兼容性（比如CSS变量或新特性），可以尝试添加独立的loader规则：

   const { override, addWebpackModuleRule } = require('customize-cra');
   
   module.exports = override(
     addWebpackModuleRule({
       test: /\.css$/,
       include: /ag-grid-community\/styles/,
       use: [
         'style-loader',
         {
           loader: 'css-loader',
           options: {
             importLoaders: 1,
             modules: false,
           },
         },
         'postcss-loader',
       ],
     })
   );
   

4. 重新启动项目
   执行npm start或npm run build，检查报错是否消失。

其他排查方向 #

• 检查依赖版本冲突：执行npm ls ag-grid-community，确认没有同时安装v27和v28版本的Ag-Grid，如有冲突，执行npm uninstall ag-grid-community后重新安装v28。
• 验证CSS文件完整性：删除node_modules和package-lock.json（或yarn.lock），重新执行npm install，确保Ag-Grid的CSS文件没有损坏。
• 尝试降级Ag-Grid补丁版本：如果是v28.x的某个特定版本存在问题，可以尝试安装v28的稳定补丁版本，比如npm install ag-grid-community@28.2.1。

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