jt360front/webpack-upgrade-plan.md

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. 卸载旧依赖

npm uninstall webpack webpack-cli webpack-dev-server webpack-merge extract-text-webpack-plugin

2. 安装新依赖

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 部分:

{
  "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 包：

   npm install buffer@6.0.3 process@0.11.10 vm-browserify@1.1.2 --save
   

2. 在 webpack.base.conf.js 中添加以下配置：

   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 到最新版本：

   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 命令安装依赖：

  npm install --legacy-peer-deps
  

5. webpack-dev-server 配置变化

问题描述：升级后开发服务器无法正常启动。

原因：webpack-dev-server 4.x 配置方式有较大变化。

解决方案：

1. 更新 webpack.dev.conf.js 中的 devServer 配置：

   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 脚本：

   {
     "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 配置中各属性名的单引号：

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"：

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

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