老旧React应用升级React+Storybook至Vite的可行性及问题咨询

核心问题 #

旧应用基于Node 12.16.1（对应Webpack 4左右版本），其Webpack的CSS处理逻辑无法兼容Vite默认输出的现代CSS模块格式，导致嵌入微前端时出现解析错误。

解决方案 #

1. 调整Vite组件库的构建输出配置 #

Vite默认的CSS打包逻辑和旧Webpack不匹配，需要修改vite.config.js，让输出产物兼容旧环境：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: './src/index.js',
      name: 'YourUIComponents',
      formats: ['umd', 'es'], // 同时输出UMD（兼容旧Webpack）和ES模块
      fileName: (format) => `your-ui-components.${format}.js`,
    },
    rollupOptions: {
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
        },
      },
    },
    cssCodeSplit: false, // 关闭CSS代码分割，将所有CSS内联到JS或打包为单个文件
  },
  css: {
    devSourcemap: false,
    postcss: {
      plugins: [
        require('postcss-preset-env')({
          browsers: ['last 2 versions', 'ie >= 11'], // 适配旧应用的目标浏览器
        }),
      ],
    },
  },
});

2. 更新旧应用的Webpack CSS规则 #

针对组件库的CSS文件，调整loader参数以兼容Vite输出的格式：

const path = require('path');

module.exports = {
  // ...其他配置
  module: {
    rules: [
      // ...其他规则
      {
        test: /\.s[ac]ss$/i,
        include: [
          path.resolve(__dirname, 'src'),
          path.resolve(__dirname, 'node_modules/your-ui-components'), // 明确包含组件库路径
        ],
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              modules: false, // 组件库未使用CSS模块时禁用，避免解析冲突
              importLoaders: 1,
              url: false, // 禁用CSS中的资源URL解析，避免旧Webpack处理出错
            },
          },
          {
            loader: 'sass-loader',
            options: {
              sassOptions: {
                includePaths: [path.resolve(__dirname, 'node_modules')],
              },
            },
          },
        ],
      },
    ],
  },
};

3. 降级组件库的CSS语法（可选） #

如果旧应用的sass-loader版本过低（如v8.x及以下），无法解析现代Sass语法（如嵌套、新变量语法），需要在组件库中调整：

• 避免使用Sass的最新特性，或者在Vite中配置转译为兼容旧版本的语法：

// vite.config.js
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        quietDeps: true,
      },
    },
  },
});

4. 独立引入组件库CSS（兜底方案） #

如果上述配置仍无法解决问题，可将组件库的CSS单独打包并手动引入旧应用：

1. 在Vite配置中开启cssCodeSplit: true，让CSS生成单独文件
2. 将组件库打包后的your-ui-components.css复制到旧应用的静态资源目录
3. 在旧应用的index.html中添加：<link rel="stylesheet" href="/static/css/your-ui-components.css">
4. 修改旧应用Webpack规则，排除组件库的CSS文件：

{
  test: /\.s[ac]ss$/i,
  exclude: [path.resolve(__dirname, 'node_modules/your-ui-components')],
  use: ['style-loader', 'css-loader', 'sass-loader'],
}

关于Node版本兼容的说明 #

完全可以将UI组件库升级至Vite（Node 18+/20+），组件库的构建环境与旧应用的运行环境相互独立，只要保证组件库的输出产物兼容旧应用的Webpack版本和Node 12的运行环境即可。

内容的提问来源于stack exchange，提问作者Félix Jiménez González