Webpack 5迁移后SSR页面首屏FOUC问题求助

问题背景 #

将采用SSR首屏加载、客户端路由的网站从Webpack 3升级到Webpack 5后，出现以下异常：

• 首屏加载时出现FOUC（无样式内容闪烁），站内导航样式显示正常
• 关闭浏览器JavaScript后，升级后的网站样式完全无法显示（Webpack 3版本可正常显示）
• 尝试在服务端配置中添加style-loader后，网站出现Cannot GET /访问错误

问题根源 #

Webpack 5中MiniCssExtractPlugin在SSR场景下的行为与Webpack 3存在差异：

1. 服务端打包时使用MiniCssExtractPlugin会将样式提取为单独文件，但SSR过程中未将这些样式注入到输出HTML中，导致首屏样式依赖客户端JS加载，引发FOUC
2. 关闭JS后，客户端无法加载提取出的CSS文件，因此样式完全丢失
3. style-loader依赖浏览器DOM环境，直接在服务端Node环境中使用会触发DOM操作错误，导致服务端无法正常响应请求

解决方案 #

1. 拆分服务端与客户端的CSS处理逻辑 #

• 服务端仅生成CSS Modules的类名映射，不处理样式提取或注入
• 客户端保持使用MiniCssExtractPlugin提取样式为独立文件，确保浏览器可直接加载

2. 修改服务端Webpack配置 #

移除服务端的MiniCssExtractPlugin，替换为css-loader/locals处理CSS文件：

require('dotenv').config({ silent: true });
const path = require('path');
const webpack = require('webpack');

const includePaths = [path.resolve(__dirname, 'stylesheets')];

module.exports = {
  bail: true,
  entry: {
    main: './src/entry-server',
  },
  output: {
    path: path.join(__dirname, 'build', 'prerender'),
    filename: '[name].js',
    publicPath: '/bundle/',
    libraryTarget: 'commonjs2',
  },
  plugins: [
    new webpack.DefinePlugin({
      'process.env': {
        NODE_ENV: JSON.stringify('production'),
        PRERENDER: true,
        ASSETS_CDN_PREFIX: JSON.stringify(process.env.ASSETS_CDN_PREFIX || ''),
      },
    }),
    // 仅加载moment英文 locale
    new webpack.ContextReplacementPlugin(/moment[\\/]locale$/, /^\.\/(en)$/),
    new webpack.optimize.ModuleConcatenationPlugin(),
    // 移除服务端的MiniCssExtractPlugin
  ],
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        include: path.join(__dirname, 'src'),
        use: 'babel-loader',
      },
      {
        test: /\.s?css$/,
        use: [
          // 服务端使用css-loader/locals，仅生成类名映射，不处理样式输出
          {
            loader: 'css-loader/locals',
            options: {
              modules: true,
            },
          },
          'postcss-loader',
          {
            loader: 'sass-loader',
            options: {
              sassOptions: {
                includePaths,
                data: `$assetprefix: "${process.env.ASSETS_CDN_PREFIX || ''}";`,
              },
            },
          },
        ],
      },
      {
        test: /\.svg$/,
        use: `svg-inline-loader?removeTags&removingTags[]=${['defs', 'style', 'title'].join(',removingTags[]=')}`,
      },
    ],
  },
  resolve: {
    extensions: ['.js', '.jsx', '.css', '.scss', '.json'],
  },
  target: 'node',
};

3. 在SSR HTML模板中注入客户端CSS文件 #

利用assets-webpack-plugin生成的资源映射文件，将客户端打包好的CSS文件直接引入到SSR输出的HTML头部：

<!DOCTYPE html>
<html>
<head>
  ${helmet.title.toString()}
  ${helmet.meta.toString()}
  <!-- 直接引入客户端CSS文件，确保首屏优先加载样式 -->
  <link rel="stylesheet" href="${assets.main.css}">
</head>
<body>
  <div id="root">${content}</div>
  <script src="${assets.main.js}"></script>
</body>
</html>

效果说明 #

• 服务端使用css-loader/locals避免了Node环境下的DOM操作，解决Cannot GET /错误
• 首屏HTML直接引入CSS文件，浏览器会优先加载样式，彻底消除FOUC
• 关闭JavaScript时，浏览器仍能通过<link>标签加载CSS，样式可正常显示

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