React项目将index.html移入client文件夹后出现tap读取错误

重构React项目时，将index.html从根目录移至client文件夹后，启动开发服务器触发如下错误：

[webpack-cli] TypeError: Cannot read properties of undefined (reading 'tap')
    at exports.tap (/path-to-project/node_modules/hard-source-webpack-plugin/lib/util/plugin-compat.js:118:25)
    at new CacheSerializerFactory (/path-to-project/node_modules/hard-source-webpack-plugin/lib/CacheSerializerFactory.js:94:18)
    at HardSourceWebpackPlugin.apply (/path-to-project/node_modules/hard-source-webpack-plugin/index.js:219:36)
...

关键信息 #

• 简化版webpack.config.js配置：

const HtmlWebpackPlugin = require('html-webpack-plugin');
const HardSourceWebpackPlugin = require('hard-source-webpack-plugin');
const { propIf, isDevelopment } = require('webpack-config-utils');

module.exports = {
  // other configurations
  plugins: [
    propIf(isDevelopment(), new HardSourceWebpackPlugin()),
    new HtmlWebpackPlugin({
      template: path.join(__dirname, 'src/index.html'),
      filename: 'index.html',
      favicon: "./src/assets/images/favicon.ico",
      meta: {
        buildStamp: (new Date()).toISOString()
      }
    }),
  ],
};

• 依赖包版本：

"webpack": "^5.95.0",
"webpack-cli": "^5.1.4",
"webpack-config-utils": "^2.3.1",
"webpack-dev-server": "^5.1.0",
"webpack-subresource-integrity": "^5.2.0-rc.1",
"html-webpack-plugin": "^5.6.0",

• 目录结构变更：
  旧结构：

  project-root/
  │
  ├── src/
  │   ├── assets/
  │   └── other-src-files/
  │
  ├── index.html
  ├── webpack.config.js
  └── other-root-files/
  

  新结构：

  project-root/
  │
  ├── client/
  │   ├── index.html
  │   ├── src/
  │   ├── assets/
  │   └── other-client-files/
  │
  ├── webpack.config.js
  └── other-root-files/
  

需求：不降级Webpack的前提下修复该错误。

1. 修正文件路径配置（触发错误的直接原因） #

移动index.html后，HtmlWebpackPlugin的模板路径和favicon路径未同步更新，导致Webpack无法找到文件，进而触发依赖插件的兼容性异常。修正配置如下：

// 确保已引入path模块
const path = require('path');

module.exports = {
  // ...其他配置
  plugins: [
    // ...其他插件
    new HtmlWebpackPlugin({
      template: path.join(__dirname, 'client/index.html'), // 更新模板路径
      filename: 'index.html',
      favicon: path.join(__dirname, 'client/src/assets/images/favicon.ico'), // 更新favicon路径
      meta: {
        buildStamp: (new Date()).toISOString()
      }
    }),
  ],
};

2. 替换废弃的hard-source-webpack-plugin #

hard-source-webpack-plugin已停止维护，与Webpack 5存在严重兼容性问题。Webpack 5内置了持久化缓存功能，完全可以替代它：

module.exports = {
  // ...其他配置
  // 启用Webpack 5内置缓存
  cache: {
    type: 'filesystem',
    buildDependencies: {
      config: [__filename] // 配置文件变更时自动重置缓存
    }
  },
  plugins: [
    // 移除hard-source-webpack-plugin相关代码
    new HtmlWebpackPlugin({/* 修正后的配置 */}),
  ]
};

如果必须临时保留该插件，可安装其Webpack 5适配的分支版本（不推荐，仍有不稳定风险）：

npm uninstall hard-source-webpack-plugin
npm install --save-dev hard-source-webpack-plugin@next

3. 清理残留缓存 #

修改配置后，清理Webpack缓存和依赖缓存，避免残留问题：

# 删除Webpack缓存目录
rm -rf node_modules/.cache
# 可选：重新安装依赖解决潜在冲突
rm -rf node_modules package-lock.json
npm install

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