Vue项目从Webpack 3升级至Webpack 4的常见错误与解决方案

Webpack 3 升级至 4 概述

近期因项目需求，需要将两个现有的Vue项目从Webpack 3迁移至Webpack 4。本文记录了升级过程中的关键步骤，以及遇到的主要错误及其对应的解决方案。

基础依赖更新与 CommonsChunkPlugin 处理

首先，需更新Webpack核心包及相关插件。注意，Webpack 4引入了新的命令行工具依赖webpack-cli。

npm i -D webpack webpack-cli webpack-dev-server webpack-merge

执行npm run dev后，终端报错：Error: webpack.optimize.CommonsChunkPlugin has been removed, please use config.optimization.splitChunks instead.

错误原因：Webpack 4已移除webpack.optimize.CommonsChunkPlugin插件，官方推荐使用config.optimization.splitChunks进行代码分割配置。

html-webpack-plugin 插件适配

其次，再次运行时报错：Error: Plugin could not be registered at 'html-webpack-plugin-before-html-processing'. Hook was not found.

原因分析：Webpack升级后，html-webpack-plugin版本不兼容导致钩子注册失败。

解决方案：升级html-webpack-plugin至兼容版本。

将html-webpack-plugin升级至“^3.2.0”版本后再次运行，仍出现报错。

原因：项目中存在自定义插件，需要在每个打包生成的HTML模板中插入特定JS代码。该自定义插件基于旧版html-webpack-plugin编写，需根据Webpack 4的API规范进行重构，具体参考官方文档：https://github.com/jantimon/h...。

解决步骤如下：

第一步：通过npm安装最新测试版插件，命令为npm i -D html-webpack-plugin@next； 第二步：修改自定义插件代码以适配新API，具体修改内容如图所示。

CSS 提取插件迁移与 vue-loader 配置

继续运行，报错：Error: Chunk.entrypoints: Use Chunks.groupsIterable and filter by instanceof Entrypoint instead

原因：自Webpack v4起，不再推荐使用extract-text-webpack-plugin处理CSS，官方建议改用mini-css-extract-plugin。

解决：执行命令npm install extract-text-webpack-plugin@next尝试修复。

注意：仅更新extract-text-webpack-plugin可能无法彻底解决问题，建议直接迁移至mini-css-extract-plugin，具体操作见后续第6步。

随后报错：TypeError: Cannot read property 'vue' of undefined

原因：Webpack升级后，vue-loader未同步更新导致兼容性问题。

解决：执行npm i -D vue-loader更新该加载器。

重要提示：在Webpack 4中，必须在配置文件中显式引入并实例化相关插件，配置才会生效。

const VueLoaderPlugin = require('vue-loader/lib/plugin');
//配置中加入
plugins: [
  new VueLoaderPlugin()
],

接着遇到报错信息（具体截图见下文）。

此时应将CSS提取插件切换为mini-css-extract-plugin。

根据项目实际情况，检查并更新其他相关依赖。

"vue-style-loader": "^4.1.2",
"vue-template-compiler": "^2.6.10”,
"html-webpack-exclude-assets-plugin": "0.0.7",
"html-webpack-inline-chunk-plugin": "^1.1.1",

删除不再使用的旧版插件配置或依赖。

在Webpack配置文件的plugins数组中，添加必要的插件引用，例如VueLoaderPlugin。

模块加载语法冲突解决

浏览器控制台报错：BaseClient.js?e917:12 Uncaught TypeError: Cannot assign to read only property 'exports' of object ‘#。虽然npm run dev在终端不报错，但浏览器打开页面时控制台抛出此异常。

原因：Webpack 4之后，严格禁止混用CommonJS的exports和ES6的import语法。

解决：调整include部分的配置，确保模块加载方式符合新规范，具体配置修改如下。

以上即为本次升级的全部内容，希望对其他开发者有所帮助，欢迎继续支持本站。