Webpack 5升级后Less打包缓存偶现异常问题排查与解决

问题描述 #

Webpack从4.x升级至5.88.1并启用文件系统缓存后，出现无法稳定复现的Less编译缓存错误：缓存的编译结果丢失了父选择器，导致样式失效。Webpack 4版本无此问题。

示例Less代码 #

.hover-visible(@cls) {
  & .@{cls} {
    visibility: hidden;
  }

  &:hover {
    & .@{cls} {
      visibility: visible;
    }
  }
}

.fx-resize-pane {
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;

  &.expand {
    .left-pane {
      .hover-visible(sidebar-toggle);
    }
  }
}

缓存中的错误编译结果 #

.fx-resize-pane {
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
}
.expand .left-pane {
  visibility: hidden;
}
.expand .left-pane:hover {
  visibility: visible;
}

正确结果应包含父选择器.fx-resize-pane，即.fx-resize-pane.expand .left-pane和.fx-resize-pane.expand:hover .left-pane .sidebar-toggle

相关依赖版本 #

• webpack: 5.88.1
• webpack-cli: 5.1.4
• less: 3.11.1
• less-loader: 11.1.2

成因分析 #

1. Loader执行顺序错误：当前Less规则中style-resources-loader放在less-loader之后，导致全局样式资源注入时机滞后，混合宏（mixin）的编译上下文不一致，缓存哈希计算出现偏差。
2. Webpack 5缓存依赖追踪不完整：文件系统缓存未正确关联Less混合宏依赖的全局样式文件，当全局样式变更时，缓存未失效，复用了旧的错误编译结果。
3. 多线程编译竞态：ts/tsx规则中使用thread-loader，多线程环境下可能出现文件依赖哈希计算的竞态，偶发生成错误的缓存键。

修复方案 #

1. 调整Less Loader执行顺序 #

将style-resources-loader移至less-loader之前，确保全局样式在Less编译前注入：

{
  test: /\.less$/,
  use: [
    MiniCssExtractPlugin.loader,
    'css-loader',
    'postcss-loader',
    {
      loader: 'style-resources-loader',
      options: {
        patterns: [path.join(basePath, 'src/styles/lib/index.less')]
      }
    },
    'less-loader'
  ],
  exclude: /node_modules/
}

2. 完善Webpack缓存配置 #

补充缓存依赖追踪规则，确保全局样式变更能触发缓存失效：

cache: {
  type: "filesystem",
  buildDependencies: {
    config: [__filename],
    // 关联全局样式文件，变更时触发缓存失效
    styles: [path.join(basePath, 'src/styles/lib/index.less')]
  },
  // 排除node_modules，避免第三方包变更干扰缓存
  managedPaths: [path.join(basePath, 'node_modules')]
}

3. 优化多线程编译配置 #

给thread-loader添加缓存配置，减少竞态影响：

{
  test: /.tsx?$/,
  use: [
    {
      loader: 'thread-loader',
      options: {
        cache: true,
        cacheDirectory: path.join(basePath, 'node_modules/.cache/thread-loader')
      }
    },
    'babel-loader',
    {
      loader: 'esbuild-loader',
      options: {
        target: 'es2015',
        tsconfigRaw: require('../tsconfig.json')
      }
    }
  ],
  exclude: /node_modules/
}

4. 临时应急方案 #

若问题偶发出现，可手动清理Webpack缓存目录强制重新编译：

rm -rf node_modules/.cache/webpack

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