从Webpack v4迁移到v5后构建失败求助

问题描述 #

将项目从 Webpack v4 迁移至 v5 并更新配置后，构建失败，报错信息如下：

/node_modules/webpack/node_modules/enhanced-resolve/lib/CachedInputFileSystem.js:40
        if (error) throw error;
                   ^

TypeError: The "path" argument must be of type string. Received undefined
    at new NodeError (node:internal/errors:393:5)
    at validateString (node:internal/validators:163:11)
    at Object.resolve (node:path:1098:7)
    at afterResolveFn (/node_modules/offline-plugin/lib/index.js:213:42)
    at Hook.eval [as callAsync] (eval at create (/node_modules/webpack/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:7:1)
    at Hook.CALL_ASYNC_DELEGATE [as _callAsync] (/node_modules/webpack/node_modules/tapable/lib/Hook.js:18:14)
    at /node_modules/webpack/lib/NormalModuleFactory.js:284:30
    at eval (eval at create (/node_modules/webpack/node_modules/tapable/lib/HookCodeFactory.js:33:10), <anonymous>:15:1)
    at /node_modules/webpack/lib/NormalModuleFactory.js:591:7
    at /node_modules/webpack/lib/NormalModuleFactory.js:116:11
    at /node_modules/webpack/lib/NormalModuleFactory.js:623:8
    at NormalModuleFactory.resolveRequestArray (/node_modules/webpack/lib/NormalModuleFactory.js:988:34)
    at /node_modules/webpack/lib/NormalModuleFactory.js:615:11
    at /node_modules/webpack/lib/NormalModuleFactory.js:116:11
    at /node_modules/webpack/lib/NormalModuleFactory.js:678:9
    at /node_modules/webpack/lib/NormalModuleFactory.js:859:5 {
  code: 'ERR_INVALID_ARG_TYPE'
}

环境信息 #

• Node.js v18.12.1
• 核心依赖版本：

  {
    "webpack": "^5.76.0",
    "webpack-cli": "^5.0.1",
    "webpack-dev-middleware": "^6.0.1",
    "webpack-hot-middleware": "^2.25.3",
    "webpack-pwa-manifest": "^4.3.0"
  }
  

已尝试更新所有 loader 至最新版本（css-loader、url-loader、style-loader、svg-url-loader、file-loader 等），但仍存在 CSS 和 SVG 无法加载的问题，构建失败未解决。

解决方案 #

1. 移除 offline-plugin #

报错栈明确指向该插件代码，它已停止维护且完全不兼容 Webpack v5。Webpack v5 内置了 Workbox 相关功能，可替代其离线缓存能力：

• 卸载插件：npm uninstall offline-plugin
• 删除 Webpack 配置中所有与该插件相关的代码

2. 替换废弃的资源 loader #

Webpack v5 内置 asset 模块，无需再使用 url-loader、file-loader、svg-url-loader，这些旧 loader 与 v5 兼容性差，会导致资源加载失败：

• 卸载旧 loader：npm uninstall url-loader file-loader svg-url-loader
• 改用内置 asset 规则配置资源处理：

  module.exports = {
    module: {
      rules: [
        // 处理 CSS
        {
          test: /\.css$/i,
          use: ["style-loader", "css-loader"],
        },
        // 处理 SVG
        {
          test: /\.svg$/i,
          type: 'asset/resource', // 输出单独文件，需内联可改用 'asset/inline'
          generator: {
            filename: 'assets/[hash][ext][query]'
          }
        },
        // 处理其他资源（图片、字体等）
        {
          test: /\.(png|jpg|jpeg|gif|woff|woff2|eot|ttf|otf)$/i,
          type: 'asset/resource',
          generator: {
            filename: 'assets/[hash][ext][query]'
          }
        }
      ],
    },
  };
  

3. 检查 webpack-pwa-manifest 配置兼容性 #

该插件虽支持 Webpack v5，但需确保配置参数无异常：

• 确认 filename、publicPath 等路径参数为有效字符串，避免出现 undefined
• 示例配置：

  const WebpackPwaManifest = require('webpack-pwa-manifest');
  const path = require('path');
  
  module.exports = {
    plugins: [
      new WebpackPwaManifest({
        name: 'My App',
        short_name: 'App',
        description: 'Progressive Web App',
        background_color: '#ffffff',
        theme_color: '#414141',
        display: 'standalone',
        start_url: '/',
        filename: 'manifest.json',
        publicPath: '/',
        icons: [
          {
            src: path.resolve('src/assets/icon.png'),
            sizes: [96, 128, 192, 256, 384, 512],
            destination: 'assets/icons'
          }
        ]
      })
    ]
  };
  

4. 排查其他配置兼容性问题 #

• 移除 Webpack v4 时期的 optimization.splitChunks 旧配置，v5 有默认优化策略，按需调整即可
• 确保 mode 配置为 development 或 production，避免默认 none 模式引发异常
• 检查入口文件路径是否正确，杜绝 undefined 路径参数

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