React项目接入Webpack后出现白屏、代码分割失效、bundle体积过大问题

现有bundle体积情况如下：

1. Bundle体积过大、代码分割不生效核心原因 #

• devtool配置错误：当前使用inline-source-map，会将完整sourcemap以Base64格式直接打入bundle.js，sourcemap体积通常是业务代码的2-3倍，是包体积达到19MB的核心诱因。
• 未开启Webpack层面代码分割规则：即使React侧写了React.lazy/loadable-components等分割逻辑，没有主动配置optimization.splitChunks的情况下，Webpack不会自动拆分公共依赖、第三方包和异步模块。
• output文件名写死：当前output.filename固定为bundle.js，代码分割生成的异步chunk无法正确输出，导致所有代码最终合并到同一个文件，代码分割完全不生效。
• 资源打包规则不完善：大于8KB的静态资源没有单独输出，也会被直接打入bundle进一步增大体积。

2. 启动白屏核心原因 #

• 路由适配问题：如果使用BrowserHistory模式路由，devServer未开启historyApiFallback: true，非根路径访问时资源加载失败直接白屏。
• 大体积包加载阻塞：19MB的JS包加载、解析、执行耗时过长，会长期处于白屏状态直到JS执行完成才会渲染页面。
• 静态资源路径匹配错误：publicPath配置和实际部署/开发路径不一致时，资源加载404会触发白屏。

3. 修复后的Webpack配置参考 #

/* eslint-disable no-undef */
const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
const HtmlWebpackInjectPreload = require("@principalstudio/html-webpack-inject-preload");
const { CleanWebpackPlugin } = require("clean-webpack-plugin");

module.exports = {
  entry: path.resolve(__dirname, './index.js'),
  // 开发环境用轻量sourcemap，生产环境单独输出sourcemap不打入bundle
  devtool: process.env.NODE_ENV === 'production' ? 'source-map' : 'cheap-module-source-map',
  output: {
    path: path.resolve(__dirname, "build"),
    // 支持多chunk输出，搭配contenthash做长期缓存
    filename: '[name].[contenthash:8].js',
    chunkFilename: '[name].[contenthash:8].chunk.js',
    publicPath: '/'
  },
  // 开启代码分割
  optimization: {
    splitChunks: {
      chunks: 'all', // 同时分割同步、异步代码
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          priority: -10,
          reuseExistingChunk: true
        }
      }
    },
    runtimeChunk: 'single'
  },
  devServer: {
    contentBase: path.resolve(__dirname, 'build'),
    port: 4000,
    hot: true,
    // 适配BrowserRouter路由，解决非根路径白屏问题
    historyApiFallback: true
  },
  resolve: {
    // 去掉.*后缀匹配，避免匹配非预期文件拖慢打包速度、引入错误资源
    extensions: [".js", ".jsx", ".css"],
    fallback: {
      stream: false
    }
  },
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /(node_modules)/,
        use: ["babel-loader"],
      },
      {
        test: /\.css$/,
        exclude: /\.module\.css$/,
        use: ["style-loader", "css-loader"],
      },
      {
        test: /\.module\.css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: { importLoaders: 2, modules: true },
          },
          "postcss-loader",
        ],
      },
      {
        test: /\.(jpe?g|png|gif|woff|woff2|eot|ttf|svg)(\?[a-z0-9=.]+)?$/,
        use: [
          {
            loader: "url-loader",
            options: {
              limit: 8192,
              // 大于8KB的资源单独输出，不打入bundle
              name: 'static/media/[name].[hash:8].[ext]'
            },
          },
        ],
      },
    ],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: path.resolve('./index.html')
    }),
    new CleanWebpackPlugin(),
    new HtmlWebpackInjectPreload({
      files: [
        {
          match: /.*\.woff2$/,
          attributes: { as: "font", type: "font/woff2", crossorigin: true },
        },
        {
          match: /\.[a-z-0-9]*.css$/,
          attributes: { as: "style" },
        },
      ],
    }),
  ],
};

4. 后续优化建议 #

• 生产环境开启mode: 'production'，Webpack会自动启动代码压缩、tree-shaking，剔除无用代码进一步减小包体积。
• 安装webpack-bundle-analyzer插件分析包构成，排查重复引入的第三方依赖，体积过大的依赖可替换为更轻量的实现。
• 非首屏组件统一使用React.lazy+Suspense做异步加载，避免打入首屏包。

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