《实战：如何搭建一个完整的 Vue2.0 项目》- 7、Vue2.x 项目 webpack 4 升级 5（半自动升级）

前言

基于 Vue2.x 的项目和组件库开发于 2019 年 ，那时对 Webpack 版本没有概念，项目和组件库的版本混乱…有的使用 v3，有的使用 v4…
对于现今 2023 年（或 2024 年）的整个生态环境是不够用的，无法使用较新和更优秀的插件。所以升级势在必行！
注意 本篇是基于 Vue2.x 组件库 的升级，如果想了解 基于 Vue2.x 项目 的升级。
请移步《Vue2.x 组件库 Webpack3 升 5》

实现

自动升级

先全局安装升级插件

npm i npm-check npm-check-updates -g
1

检查依赖

npm-check
1

更新检查后的依赖并展示版本号，此时 package.json还没有更新

npm-check-updates
1

升级 package.json，下图显示更新版本，此时 package.json文件已变更。但我们是更新webpack，vue还是使用v2，先手动改回原来的版本号。

ncu -u
1

package.json中删除无用插件

"cache-loader": "4.1.0",
1

清理缓存和依赖，非常有必要，避免冗余插件，且会报奇怪的错误。或直接删除 node_modules 文件夹；

npm cache clean --force
npm install --legacy-peer-deps
1
2

删除原有 package-lock.json，安装依赖

npm install
1

启动时报错

错误 1： Error: Cannot call .tap() on a plugin that has not yet been defined. Call plugin('preload').use() first

解决方案： vue.config.js 中删除如下代码，暂无配置需要

config.plugin('preload').tap(() => [
    {
        rel: 'preload',
        fileBlacklist: [/\.map$/, /hot-update\.js$/, /runtime\..*\.js$/],
        include: 'initial'
    }
])

config
    .plugin('ScriptExtHtmlWebpackPlugin')
    .after('html')
    .use('script-ext-html-webpack-plugin', [{
        // `runtime` must same as runtimeChunk name. default is `runtime`
        inline: /runtime\..*\.js$/
    }])
    .end()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

错误 2： webpack < 5 used to include polyfills for node.js core modules by default.

解决方案： 安装 npm install path-browserify，vue.config.js 中配置

module.exports = {,
    configureWebpack: {
        resolve: {
            fallback: { path: require.resolve("path-browserify") },
        }
    }
}
1
2
3
4
5
6
7

错误 3： Invalid options object. Dev Server has been initialized using an options object that does not match the API schema.

解决方案： 再嵌套一层，overlay 放在 client 中

// 错误
module.exports = {
    devServer: {
        overlay: {
            warnings: false,
            errors: true
        },
    }
}
// 正确 要套在 client 属性下
module.exports = {
    devServer: {
        client: {
            // https://webpack.docschina.org/configuration/dev-server/#overlay
            overlay:false,//禁止：当出现编译错误或警告时，在浏览器中显示全屏覆盖
        }
    }     
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

错误 4： export 'default' (imported as 'pathToRegexp') was not found in 'path-to-regexp'

解决方案： 从 v2.4.0 升级到 v6.2.1，要做如下调整。文件src\components\admin\Breadcrumb\index.vue

报错
import pathToRegexp from 'path-to-regexp'
正确
import * as pathToRegexp from 'path-to-regexp'
1
2
3
4

错误 5： PostCSS Loader has been initialized using an options object that does not match the API schema

解决方案： 再嵌套一层，plugins 放在 postcssOptions

//报错，适合 webpack 4-
css: {
    loaderOptions: {
        postcss: {
            plugins: [
                require('postcss-pxtorem')({ // 把px单位换算成rem单位
                    rootValue: 16, // 16px = 1rem
                        unitPrecision: 5,
                        propList: ['*'],
                        replace: true,
                        mediaQuery: false,
                        minPixelValue: 0
            	})
            ]
        }
    }
}
// 正确：需要再嵌套一层 postcssOptions
css: {
    loaderOptions: {
        postcss: {
            postcssOptions: {
                plugins: [
                    require('postcss-pxtorem')({ // 把px单位换算成rem单位
                        rootValue: 16, // 16px = 1rem
                            unitPrecision: 5,
                            propList: ['*'],
                            replace: true,
                            mediaQuery: false,
                            minPixelValue: 0
                	})
                ]
            }
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

启动后报错

错误 1： CSS 中 background: url(...) 图片路径错误

解决方案： 貌似无法使用相对路径，要使用绝对路径。如果图片在 public/images

// 报错：暂不理解为啥 webpack5 不可行，或是有其它配置未更新
background: url('/images/tools/bg-selected.png');
// 正确
background: url('../../../../public/images/tools/bg-selected.png');
// 正确(推荐)：或把图片放 src/assets/images 下。避免多层级嵌套
background: url('@/assets/images/tools/bg-selected.png');
1
2
3
4
5
6

错误 2： 后台管理系统 sass变量export 失败

解决方案： 文件 src\layout\components\Sidebar\index.vue 。参考 VueCLI CSS Modules，Vite 也有类似说明，参考 Vite CSS Modules

// 错误：导出对象为空
import variables from '@/styles/variables.scss'
// 正确：新增前缀.module，被认为是一个CSS模块文件，导入时会返回一个相应的模块对象
import variables from '@/styles/variables.module.scss'
1
2
3
4

最后

想要了解更多，请查看官网 《从 v4 升级到 v5》