# 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 语法

虽然升级过程中遇到了一些挑战，但通过逐一解决问题，最终成功完成了升级，为项目后续的维护和性能优化奠定了基础。