yindongqi
d24052d24b
主要变更包括： 1. 更新Babel配置，使用@babel/preset-env和@babel/plugin-transform-object-rest-spread。 2. 升级Webpack及相关插件，使用MiniCssExtractPlugin替代ExtractTextPlugin。 3. 更新package-lock.json和package.json，调整依赖版本。 4. 修改README.md，更新项目简介和环境要求。 5. 代码格式优化和错误处理增强，提升构建和开发体验。
231 lines
6.8 KiB
Markdown
231 lines
6.8 KiB
Markdown
# Webpack 3 升级到 Webpack 5 详细计划
|
||
|
||
## 升级背景
|
||
当前项目使用 Webpack 3.6.0，需要升级到 Webpack 5 以支持 Node.js 18，并提升构建性能和安全性。
|
||
|
||
## 升级前准备
|
||
1. 备份项目代码和 `package.json` 文件
|
||
2. 确保已安装 Node.js 18+（当前计划使用版本）
|
||
3. 了解 Webpack 3 与 Webpack 5 的主要差异
|
||
|
||
## 升级步骤
|
||
|
||
### 1. 卸载旧依赖
|
||
```bash
|
||
npm uninstall webpack webpack-cli webpack-dev-server webpack-merge extract-text-webpack-plugin
|
||
```
|
||
|
||
### 2. 安装新依赖
|
||
```bash
|
||
npm install webpack@5.88.2 webpack-cli@5.1.4 webpack-dev-server@4.15.1 webpack-merge@5.9.0 mini-css-extract-plugin@2.7.6 --save-dev
|
||
npm install html-webpack-plugin@5.5.3 --save-dev
|
||
npm install vue-loader@15.10.1 --save-dev
|
||
```
|
||
|
||
### 3. 更新 package.json 脚本
|
||
修改 `package.json` 中的 scripts 部分:
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"dev": "webpack serve --config build/webpack.dev.conf.js --host 0.0.0.0",
|
||
"build": "node build/build.js"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 修改 Webpack 配置文件
|
||
|
||
#### 4.1 修改 webpack.base.conf.js
|
||
- 添加 VueLoaderPlugin
|
||
- 更新 module.rules 配置
|
||
- 调整输出配置
|
||
|
||
#### 4.2 修改 webpack.dev.conf.js
|
||
- 更新 devServer 配置
|
||
- 修改插件配置
|
||
|
||
#### 4.3 修改 webpack.prod.conf.js
|
||
- 替换 extract-text-webpack-plugin 为 mini-css-extract-plugin
|
||
- 更新优化配置
|
||
- 移除过时插件
|
||
|
||
### 5. 解决可能的兼容性问题
|
||
- 处理 Babel 配置
|
||
- 更新其他 loader 版本
|
||
- 解决依赖冲突
|
||
|
||
## 主要变化点
|
||
1. Webpack 5 内置更多功能，减少对第三方插件的依赖
|
||
2. 开发服务器配置变化 (webpack-dev-server -> webpack serve)
|
||
3. 提取 CSS 的插件变化 (extract-text-webpack-plugin -> mini-css-extract-plugin)
|
||
4. 模块解析和优化配置的变化
|
||
5. 缓存机制改进
|
||
|
||
## 可能遇到的问题及解决方案
|
||
1. **Node.js 版本兼容问题**：确保使用 Node.js 18+
|
||
2. **插件不兼容**：逐一替换为 Webpack 5 兼容版本
|
||
3. **配置语法变化**：更新配置文件以符合 Webpack 5 语法
|
||
4. **依赖冲突**：使用 npm ls 检查并解决冲突
|
||
|
||
## 测试计划
|
||
1. 升级后运行 `npm run dev` 测试开发环境
|
||
2. 运行 `npm run build` 测试生产构建
|
||
3. 检查应用功能是否正常
|
||
4. 验证构建输出文件大小和性能
|
||
|
||
## 实际升级问题及解决方案
|
||
|
||
在实际升级过程中，我们遇到了以下问题并成功解决：
|
||
|
||
### 1. Node.js 核心模块未定义问题 (Buffer, process)
|
||
|
||
**问题描述**：升级到 Webpack 5 后，浏览器中出现 `Buffer is not defined` 和 `process is not defined` 错误。
|
||
|
||
**原因**：Webpack 5 不再自动 polyfill Node.js 核心模块，需要手动添加。
|
||
|
||
**解决方案**：
|
||
1. 安装必要的 polyfill 包：
|
||
```bash
|
||
npm install buffer@6.0.3 process@0.11.10 vm-browserify@1.1.2 --save
|
||
```
|
||
|
||
2. 在 webpack.base.conf.js 中添加以下配置：
|
||
```javascript
|
||
const webpack = require('webpack');
|
||
|
||
module.exports = {
|
||
// ... 其他配置
|
||
resolve: {
|
||
fallback: {
|
||
buffer: require.resolve('buffer/'),
|
||
process: require.resolve('process/'),
|
||
vm: require.resolve('vm-browserify')
|
||
}
|
||
},
|
||
plugins: [
|
||
// ... 其他插件
|
||
new webpack.ProvidePlugin({
|
||
Buffer: ['buffer', 'Buffer'],
|
||
process: 'process/browser'
|
||
})
|
||
]
|
||
};
|
||
```
|
||
|
||
### 2. Node.js 18 与 node-sass 兼容性问题
|
||
|
||
**问题描述**：在 Node.js 18 环境下，使用旧版本 node-sass 导致编译错误。
|
||
|
||
**原因**：node-sass 4.x 不兼容 Node.js 18。
|
||
|
||
**解决方案**：
|
||
1. 升级 node-sass 到最新版本：
|
||
```bash
|
||
npm install node-sass@9.0.0 --save-dev --legacy-peer-deps
|
||
```
|
||
|
||
2. 使用 `--legacy-peer-deps` 标志解决与 webpack 5 的依赖冲突。
|
||
|
||
> 注意：node-sass 已被弃用，建议未来迁移到 sass 或 sass-embedded。
|
||
|
||
### 3. pkcs7 包引擎版本不兼容警告
|
||
|
||
**问题描述**：安装依赖时出现 pkcs7 包要求 node@^0.10 的警告。
|
||
|
||
**原因**：项目依赖的 pkcs7 包版本过旧，与 Node.js 18 不兼容。
|
||
|
||
**解决方案**：
|
||
- 目前可以忽略此警告，不影响项目运行。
|
||
- 建议未来更新此包到兼容版本。
|
||
|
||
### 4. 依赖安装冲突
|
||
|
||
**问题描述**：安装新依赖时出现多个包版本冲突。
|
||
|
||
**原因**：不同包对同一个依赖的版本要求不一致。
|
||
|
||
**解决方案**：
|
||
- 使用 `npm install --legacy-peer-deps` 命令安装依赖：
|
||
```bash
|
||
npm install --legacy-peer-deps
|
||
```
|
||
|
||
### 5. webpack-dev-server 配置变化
|
||
|
||
**问题描述**：升级后开发服务器无法正常启动。
|
||
|
||
**原因**：webpack-dev-server 4.x 配置方式有较大变化。
|
||
|
||
**解决方案**：
|
||
1. 更新 webpack.dev.conf.js 中的 devServer 配置：
|
||
```javascript
|
||
devServer: {
|
||
host: '0.0.0.0',
|
||
port: 8080,
|
||
client: {
|
||
overlay: { warnings: false, errors: true },
|
||
},
|
||
historyApiFallback: true,
|
||
proxy: {
|
||
'/api': {
|
||
target: 'http://sz-test.shengzhevictor.com',
|
||
changeOrigin: true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
2. 更新 package.json 中的 dev 脚本：
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"dev": "webpack serve --config build/webpack.dev.conf.js --host 0.0.0.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. resolve.fallback 配置引号问题
|
||
|
||
**问题描述**：Webpack 5 配置验证错误，提示 resolve.fallback 配置中的属性名不能带引号。
|
||
|
||
**原因**：Webpack 5 对配置格式有更严格的要求，resolve.fallback 中的属性名应该是标识符而非字符串。
|
||
|
||
**解决方案**：
|
||
修改 webpack.base.conf.js 文件，移除 resolve.fallback 配置中各属性名的单引号：
|
||
```javascript
|
||
resolve: {
|
||
fallback: {
|
||
crypto: require.resolve('crypto-browserify'),
|
||
stream: require.resolve('stream-browserify'),
|
||
buffer: require.resolve('buffer/'),
|
||
process: require.resolve('process/'),
|
||
vm: require.resolve('vm-browserify')
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. devtool 配置格式问题
|
||
|
||
**问题描述**：Webpack 5 配置验证错误，提示 configuration.devtool 不符合模式 "^(inline-|hidden-|eval-)?(nosources-)?(cheap-(module-)?)?source-map(-debugids)?$"
|
||
|
||
**原因**：Webpack 5 对 devtool 配置格式有严格要求，不再支持以 "#" 开头的格式。
|
||
|
||
**解决方案**：
|
||
修改 config/index.js 文件，将 build.devtool 的值从 "#source-map" 改为 "source-map"：
|
||
```javascript
|
||
build: {
|
||
// ... 其他配置
|
||
devtool: 'source-map',
|
||
// ... 其他配置
|
||
}
|
||
```
|
||
|
||
## 升级总结
|
||
|
||
1. 成功将 Webpack 从 3.6.0 升级到 5.88.2
|
||
2. 解决了 Node.js 18 兼容性问题，使项目能够在现代 Node.js 环境下运行
|
||
3. 添加了必要的 Node.js 核心模块 polyfill
|
||
4. 解决了依赖冲突和插件兼容性问题
|
||
5. 更新了构建配置以符合 Webpack 5 语法
|
||
|
||
虽然升级过程中遇到了一些挑战，但通过逐一解决问题，最终成功完成了升级，为项目后续的维护和性能优化奠定了基础。 |