前言

在GitHub上找了一个webgl实现地图引擎的开源项目，项目最后一次更新是2016年，当时的webpack是3的版本，原定思路是按照package.json文件进行环境配置，原以为把对应版本的包装好就行，事与愿违，捣鼓了一天，项目太久远了，node webpack sass-loader等等包即便是配好了，还要浏览器支持，最终还是选择webpack3升级webpack5。
在webpack3环境搭建以及webpack升级的过程中，同样学到了很多东西，记录一下

一、webpack3环境

项目拉取下来后，直接npm install，肯定会报错，有啥错就解决，解决不了就记录下，算是给“撞南墙”给个结果

1.1、知识点记录

1.1.1、配置解释

 new HtmlWebpackPlugin({filename: './webapp.html',template: '!!ejs-loader!./src/webapp/template.html',hash: false,inject: 'body',chunks: ["webapp"]})

1. filename: ‘./webapp.html’

• 这个字段指定了输出的 HTML 文件的名称和路径。 ./webapp.html 表示该文件会被生成在构建目录的根目录下，并命名为
  webapp.html。
• template: ‘!!ejs-loader!./src/webapp/template.html’

2. template 指定了用于生成 HTML 文件的模板文件路径。

• !!ejs-loader! 表示使用 ejs-loader 来加载模板文件，并通过 ejs 引擎处理它。!! 是 Webpack 中的一种特殊语法，表示强制忽略所有的默认 loader 配置，直接使用 ejs-loader。
• ./src/webapp/template.html 是相对于项目根目录的模板文件路径，它会作为 HTML 文件的基础模板。

3. hash: false

• hash 控制是否在生成的 HTML 文件中自动为打包后的资源添加 hash 值。
• 如果设置为 false，则不在文件名后加上哈希值，通常用于资源不需要缓存控制的场景。如果你设置为 true，则会为每个资源文件添加一个哈希值，确保文件内容变化时，文件名也会变化。

4. inject: ‘body’

• inject 控制如何注入 JS 和 CSS 资源到 HTML 模板中。
• ‘body’ 表示所有的 JavaScript 文件会被注入到 HTML 文件的 标签之前，而不是 标签中。
• 另外，还可以设置为 ‘head’，此时会将资源注入到 标签中。

5. chunks: [“webapp”]

• chunks 指定了要在生成的 HTML 文件中引入的 JavaScript 文件的名称。
• [“webapp”] 表示只有名为 webapp 的 chunk 会被注入到最终的 HTML 文件中。
• 这是 Webpack 的一个优化特性，通常用来控制哪些资源需要被包含到 HTML 中。比如，如果你使用了多入口的配置，只有指定的 chunk 会被注入到 HTML 文件中。

6. 这段配置的作用是：

• 使用 ejs-loader 渲染 template.html 模板，生成最终的 webapp.html 文件。
• 在生成的 HTML 文件中，将包含 webapp chunk 相关的 JavaScript 文件，并且这些文件会被注入到 标签之前。
• 不会在文件名中添加哈希值（hash: false）。这样的配置通常用于多页面应用（MPA）或者自定义的构建场景。

最终方案：不用ejs了，用html-loader如： template: '!!html-loader!./src/core/template.html'

1.1.2、webpack与sass版本对应关系

• 对于 Webpack 5，使用 sass-loader 10.x 或更高版本，且安装 sass。
• 对于 Webpack 4，使用 sass-loader 8.x 或 9.x，建议安装 sass，但也可以使用 node-sass。
• 推荐始终使用 sass 作为 Sass 编译器，因为 node-sass 已不再维护。。

版本对应表

Webpack 版本	sass-loader 版本	sass 版本
Webpack 5	10.x 或 11.x	1.x (sass)
Webpack 4	8.x 或 9.x	1.x (sass)
Webpack 4 或 5	9.x 及以下	node-sass (旧版)

1.1.3、CommonJS与ESModule

• CommonJS 更适合 Node.js 环境，它的同步加载机制和较为简单的语法非常适合服务器端开发。
• ESModule 是现代 JavaScript 的标准模块格式，适用于浏览器和 Node.js 环境，并且支持更强大的特性，如静态分析和 Tree Shaking。

CommonJS与ESModule的区别对比

特性	CommonJS	ESModule (ESM)
加载方式	同步加载（适用于服务器端）	异步加载（适用于浏览器端和服务器端）
模块导出	module.exports 或 exports	export 和 export default
模块导入	require()	import
模块解析	动态解析，运行时解析模块	静态解析，编译时解析模块（支持静态优化，如 Tree Shaking）
运行时支持	完全支持（Node.js）	浏览器和 Node.js（需要启用或使用特定的扩展名）
支持的特性	适用于 Node.js 环境，且支持同步导入	原生支持 ES6 模块化，适合浏览器与服务器端
模块作用域	模块内共享状态，exports 可以被修改	每个模块都有独立的作用域，不能修改导入的内容
编译时优化	不支持静态优化，如 Tree Shaking	支持静态分析和优化（例如 Tree Shaking）

1.1.4、node版本管理nvm

注意：

• 建议安装nvm前卸载掉之前的node
• cmd命令行需要超级管理员模式

1. nvm安装包下载
   下载地址：nvm下载地址

2. node所有的版本
   版本地址：Node所有版本号

3. 常用命令

   nvm -v 查看当前版本
   nvm --config 
   nvm list 查看已安装node版本列表
   nvm install 版本号 下载对应node版本（如：nvm install 14.20.1）
   nvm use 版本号 切换node版本
   nvm on 开启nvm
   nvm off 关闭nvm	
   

1.1.5、sass-loader、sass与node-sass

• sass-loader 是 Webpack 的加载器，用于处理 Sass 文件并交给编译器。
  • 功能: sass-loader 是 Webpack 的一个加载器（loader），用于处理和转换 Sass 文件（.scss 或 .sass）到普通的 CSS。它会调用 Sass 编译器（比如 node-sass 或 dart-sass）将 Sass 代码编译成 CSS 代码。
  • sass-loader 必须依赖一个 Sass 编译器（node-sass 或 sass）来完成实际的编译过程。sass-loader 本身并不执行编译，而是通过配置调用具体的 Sass 编译器。
  • 在 Webpack 配置文件中，通常你需要将 sass-loader 放在一系列 CSS 相关的加载器中（如 style-loader 和 css-loader）：

  {test: /\.scss$/,use: ['style-loader',  // 将 CSS 插入到页面中'css-loader',    // 解析 CSS 文件'sass-loader'    // 编译 Sass 到 CSS]
  }

• node-sass 是一个基于 C++ 的Sass 编译器（已逐渐被 sass 取代）。
  • 功能: node-sass 是一个用于将 Sass（.scss 或 .sass 文件）编译为 CSS 的 Node.js 库。它是基于 LibSass（一个 C 语言编写的 Sass 编译器）构建的，用于快速编译 Sass 文件。
• sass 是基于 Dart 的官方 Sass 编译器，推荐在新项目中使用。
  • 功能: sass 是 Dart 语言编写的 Sass 编译器，是 node-sass 的替代方案。随着 node-sass 停止更新和维护，官方推荐使用 sass（Dart 编写的版本）。

1.2、其他

1.2.1、.d.ts是什么文件

在 TypeScript 中，.d.ts 文件用于为外部库、第三方模块或纯 JavaScript 代码提供类型定义，而不需要将这些库或模块的源代码直接转换为 TypeScript 代码。这样，TypeScript 能够使用这些外部模块时，享受类型检查和代码补全的好处。
声明文件并不包含实际的代码实现，而只是提供类型信息，告诉 TypeScript 编译器有关某个模块、类、函数、变量、接口等的类型信息。

1.2.2、react与@types/react版本对应关系

在 React 项目中，react 和 @types/react 是两个关键的依赖包，它们提供了 React 库的功能和类型定义。为了确保项目中 TypeScript 类型的正确性和一致性，react 和 @types/react 需要保持一定的版本对应关系。这里是一些常见的版本对应关系，以及如何选择和配置它们：

1. React 与 @types/react 版本对应表

React 版本	@types/react 版本	TypeScript 支持版本
React 18.x	@types/react 18.x	TypeScript 4.4+
React 17.x	@types/react 17.x	TypeScript 4.1+
React 16.x	@types/react 16.x	TypeScript 3.7+
React 15.x	@types/react 15.x	TypeScript 2.x+

1.2.3、webpack5需要的node版本

Webpack 5 需要 Node.js 版本 10.13.0 或更高版本。为了确保最佳的性能和兼容性，推荐使用 Node.js 14.x 或 Node.js 16.x 版本。
具体说明：

• Webpack 5 在 2020 年发布，要求 Node.js 10.13.0 及以上版本。
• 对于长期支持 (LTS) 版本，建议使用 Node.js 14.x 或 16.x，因为它们得到长期的安全更新和支持。
• 请注意，Webpack 5 不支持 Node.js 8.x 或更低版本。

二、webpack3升级到webpack5

2.1、更新 package.json 文件中的所有依赖项

更新 package.json 文件中的所有依赖项

2.1.1、npm-check-updates安装

npm install -g npm-check-updates

2.1.2、检查更新依赖

ncu -u

• ncu -u 会更新 package.json 文件中的依赖项版本号

2.1.3、安装依赖

npm install

• npm install 会安装更新后的依赖项。

2.1.4、问题

• npm install问题
  在使用ncu -u更新package.json中的依赖版本后，直接install会报如下错，

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: webglobe@0.6.3
npm error Found: webpack@5.97.1
npm error node_modules/webpack
npm error   dev webpack@"^5.97.1" from the root project
npm error
npm error Could not resolve dependency:
npm error peer webpack@"^3.1.0" from extract-text-webpack-plugin@3.0.2
npm error node_modules/extract-text-webpack-plugin
npm error   dev extract-text-webpack-plugin@"^3.0.2" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.

• 解决办法
  • 清缓存：npm cache clean --force
  • 忽略冲突安装npm install --legacy-peer-deps
    • --legacy-peer-deps 选项告诉 npm 使用旧的 peer dependencies 处理方式，即不会自动安装 peer dependencies，而是由用户手动管理。这样可以避免因 peer dependencies 冲突而导致的安装失败。

2.2、修改webpack.cong.js

• 移除 ExtractTextWebpackPlugin，因为它在 Webpack 5 中已被弃用，取而代之的是 MiniCssExtractPlugin。 移除了 WebpackMd5Hash，因为 Webpack 5 已经默认支持内容哈希。 更新了
• HtmlWebpackPlugin 的配置，使其更符合 Webpack 5 的语法。
• 更新 module.rules 中的 loader 语法，使其更符合 Webpack 5 的语法。 添加了 optimization 配置，以启用 CSS 压缩。
• 更新plugins中的 DefinePlugin 配置，使其更符合 Webpack 5 的语法。
• 更新process.argv.indexOf(“–ci”) 中的 plugin 语法，使其更符合 Webpack 5 的语法。

2.3、标准webpack5配置文件

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');module.exports = {// 模式配置，可以是 'development' 或 'production'mode: 'development',// 入口文件entry: {main: './src/index.js', // 你的主入口文件},// 输出配置output: {filename: '[name].[contenthash].js', // 输出文件名，使用 contenthash 以便缓存管理path: path.resolve(__dirname, 'dist'), // 输出路径clean: true, // 在每次构建前清理输出目录},// 模块解析配置module: {rules: [// JavaScript 解析{test: /\.js$/,exclude: /node_modules/,use: {loader: 'babel-loader',options: {presets: ['@babel/preset-env'],},},},// CSS 解析{test: /\.css$/,use: [MiniCssExtractPlugin.loader, 'css-loader'],},// 图片文件解析{test: /\.(png|svg|jpg|jpeg|gif)$/i,type: 'asset/resource',generator: {filename: 'images/[hash][ext][query]', // 输出图片文件名},},// 字体文件解析{test: /\.(woff|woff2|eot|ttf|otf)$/i,type: 'asset/resource',generator: {filename: 'fonts/[hash][ext][query]', // 输出字体文件名},},],},// 插件配置plugins: [new CleanWebpackPlugin(), // 清理输出目录new HtmlWebpackPlugin({template: './src/index.html', // 模板文件filename: 'index.html', // 输出文件名}),new MiniCssExtractPlugin({filename: 'styles/[name].[contenthash].css', // 输出 CSS 文件名}),],// 开发服务器配置devServer: {contentBase: path.join(__dirname, 'dist'), // 服务器的输出目录compress: true, // 启用 gzip 压缩port: 9000, // 端口号open: true, // 自动打开浏览器},// 优化配置optimization: {moduleIds: 'deterministic', // 确定性的模块 IDruntimeChunk: 'single', // 为每个入口创建一个运行时文件splitChunks: {cacheGroups: {vendor: {test: /[\\/]node_modules[\\/]/,name: 'vendors',chunks: 'all',},},},},// 解析配置resolve: {extensions: ['.js', '.json', '.jsx', '.css'], // 自动解析确定的扩展alias: {'@': path.resolve(__dirname, 'src/'), // 设置路径别名},},
};

三、问题记录

3.1、node版本低的问题

npm WARN deprecated core-js@2.6.12: core-js@<3.23.3 is no longer maintained and not recommended for usage due to the number of issues. Because of the V8 engine whims, feature detection in old core-js versions could cause a slowdown up to 100x even if nothing is polyfilled. Some versions have web compatibility issues. Please, upgrade your dependencies to the actual version of core-js.
npm WARN deprecated core-js@1.2.7: core-js@<3.23.3 is no longer maintained and not recommended for usage due to the number of issues. Because of the V8 engine whims, feature detection in old core-js versions could cause a slowdown up to 100x even if nothing is polyfilled. Some versions have web compatibility issues. Please, upgrade your dependencies to the actual version of core-js.
npm ERR! Windows_NT 10.0.22631
npm ERR! argv "C:\\Program Files\\nodejs\\node.exe" "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js" "install"
npm ERR! node v6.0.0
npm ERR! npm  v3.8.6

• 警告: core-js 被弃用
• 错误: Node.js 版本过低

3.2、node-sass问题

直接在package.json中删除这个包，node-sass包在webpack4和webpack5中被sass-loader代替了

npm error gyp ERR! find Python
npm error gyp ERR! configure error
npm error gyp ERR! stack Error: Could not find any Python installation to use
npm error gyp ERR! stack     at PythonFinder.fail (D:\Program\Vue\WebGlobe\node_modules\node-gyp\lib\find-python.js:330:47)
npm error gyp ERR! stack     at PythonFinder.runChecks (D:\Program\Vue\WebGlobe\node_modules\node-gyp\lib\find-python.js:159:21)
npm error gyp ERR! stack     at PythonFinder.<anonymous> (D:\Program\Vue\WebGlobe\node_modules\node-gyp\lib\find-python.js:228:18)
npm error gyp ERR! stack     at PythonFinder.execFileCallback (D:\Program\Vue\WebGlobe\node_modules\node-gyp\lib\find-python.js:294:16)
npm error gyp ERR! stack     at exithandler (node:child_process:430:5)
npm error gyp ERR! stack     at ChildProcess.errorhandler (node:child_process:442:5)
npm error gyp ERR! stack     at ChildProcess.emit (node:events:518:28)
npm error gyp ERR! stack     at ChildProcess._handle.onexit (node:internal/child_process:291:12)
npm error gyp ERR! stack     at onErrorNT (node:internal/child_process:483:16)
npm error gyp ERR! stack     at process.processTicksAndRejections (node:internal/process/task_queues:82:21)
npm error gyp ERR! System Windows_NT 10.0.22631
npm error gyp ERR! command "C:\\Program Files\\nodejs\\node.exe" "D:\\Program\\Vue\\WebGlobe\\node_modules\\node-gyp\\bin\\node-gyp.js" "rebuild" "--verbose" "--libsass_ext=" "--libsass_cflags=" "--libsass_ldflags=" "--libsass_library="
npm error gyp ERR! cwd D:\Program\Vue\WebGlobe\node_modules\node-sass
npm error gyp ERR! node -v v20.18.1
npm error gyp ERR! node-gyp -v v8.4.1
npm error gyp ERR! not ok
npm error Build failed with error code: 1
npm error A complete log of this run can be found in: C:\Users\bq\AppData\Local\npm-cache\_logs\2024-12-25T05_23_16_951Z-debug-0.log

3.3、webpack版本低的问题

Module build failed: ModuleBuildError: Module build failed: TypeError: this.getOptions is not a functionat Object.loader (D:\Program\Vue\WebGlobe-develop\node_modules\sass-loader\dist\index.js:19:24)at runLoaders (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\lib\NormalModule.js:195:19)at D:\Program\Vue\WebGlobe-develop\node_modules\loader-runner\lib\LoaderRunner.js:367:11at D:\Program\Vue\WebGlobe-develop\node_modules\loader-runner\lib\LoaderRunner.js:233:18at process._tickCallback (internal/process/next_tick.js:68:7)

错误 TypeError: this.getOptions is not a function 通常是由于 sass-loader 的版本和 Webpack 版本不兼容导致的。具体来说，sass-loader 9.x 版本之前不支持 Webpack 5 使用的 this.getOptions() 方法，可能是你的 Webpack 版本较高，而 sass-loader 的版本较低。

• 如果你使用的是 Webpack 5，那么需要使用 sass-loader 10.x 或更高版本。
• 如果你使用的是 Webpack 4 或更低版本，则应该使用 sass-loader 9.x 版本或更低版本

3.4、webpack版本以及插件不兼容问题

TypeError: compilation.mainTemplate.applyPluginsWaterfall is not a functionat D:\Program\Vue\WebGlobe-develop\node_modules\html-webpack-plugin\lib\compiler.js:81:51at compile (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\lib\Compiler.js:343:11)at hooks.afterCompile.callAsync.err (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\lib\Compiler.js:681:15)at AsyncSeriesHook.eval [as callAsync] (eval at create (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\node_modules\tapable\lib\HookCodeFactory.js:33:10), <anonymous>:6:1)at AsyncSeriesHook.lazyCompileHook (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\node_modules\tapable\lib\Hook.js:154:20)at compilation.seal.err (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\lib\Compiler.js:678:31)at AsyncSeriesHook.eval [as callAsync] (eval at create (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\node_modules\tapable\lib\HookCodeFactory.js:33:10), <anonymous>:6:1)at AsyncSeriesHook.lazyCompileHook (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\node_modules\tapable\lib\Hook.js:154:20)at hooks.optimizeAssets.callAsync.err (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\lib\Compilation.js:1423:35)at AsyncSeriesHook.eval [as callAsync] (eval at create (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\node_modules\tapable\lib\HookCodeFactory.js:33:10), <anonymous>:6:1)at AsyncSeriesHook.lazyCompileHook (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\node_modules\tapable\lib\Hook.js:154:20)at hooks.optimizeChunkAssets.callAsync.err (D:\Program\Vue\WebGlobe-develop\node_modules\webpack\lib\Compilation.js:1414:32)

• compilation.mainTemplate.applyPluginsWaterfall is not a function 错误表明 Webpack 在尝试调用 mainTemplate.applyPluginsWaterfall 方法时，未找到该方法。这意味着 Webpack 版本可能不再支持或已经移除了该方法，或者相关插件在新版本中存在兼容性问题。
• applyPluginsWaterfall 方法在 Webpack 5 中已被移除。在 Webpack 5 中，插件 API 做了一些改动，很多以前的方法都被移除或替换。因此，如果你的项目依赖于 Webpack 5 或更高版本，而插件仍使用了 Webpack 4 中的方法，就可能会发生这种错误。

3.5、- -colors问题

在webpack5中，一些命令行选项已经发生了变化，包括–colors选项。这个选项在webpack5中已经被移除，因为webpack5默认就会输出带有颜色的信息。

[webpack-cli] Error: Unknown option '--colors'
[webpack-cli] Run 'webpack --help' to see available commands and options

在package.json文件中直接去除掉--colors即可，如下

"scripts": {"clean": "rimraf buildOutput && rimraf index.html","prebuild:dev": "npm run clean","build:dev": "cross-env NODE_ENV=development webpack --progress","prebuild:prod": "npm run clean","build:prod": "cross-env NODE_ENV=production webpack --progress","start": "cross-env NODE_ENV=development webpack serve --open --progress","test": "cross-env NODE_ENV=development webpack --progress"
}

3.6、node-sass 的问题

由于 node-sass 使用了一个本地的二进制文件来编译 Sass，这可能会导致一些平台上的兼容性问题。为了应对这一问题，Sass 官方推荐使用 sass（即 Dart Sass）作为更现代和稳定的替代方案。sass 是基于 Dart 编程语言实现的 Sass 编译器，且不依赖本地二进制文件，更易于跨平台使用。

3.7、lib.dom.d.ts中没有layerX属性的问题

lib.dom.d.ts 文件是 TypeScript 提供的标准 DOM 类型声明文件，包含了浏览器中的 DOM API 的类型定义。关于 layerX 属性，它是一个用于旧版浏览器中的鼠标事件属性，指示鼠标相对于事件目标的水平坐标。该属性在现代浏览器中已经被弃用，并被更为标准的 clientX 和 pageX 等属性所取代。

3.8、wheelDelta 已废弃问题

TS2339: Property 'wheelDelta' does not exist on type 'WheelEvent'.

• wheelDelta 是一个已弃用的属性，最初用于在旧版浏览器（如 Internet Explorer 和早期版本的 Chrome 和 Firefox）中获取鼠标滚轮的滚动量。它的标准替代品是 Y（或者 X 和 Z，用于横向和纵向滚动），这些属性是现代浏览器所支持的。
• wheelDelta 已废弃：wheelDelta 在现代浏览器中不再使用。它被 X 和 Y 等标准化属性取代，符合 W3C 规范。TypeScript 的 DOM 类型定义已经不再包含 wheelDelta，因此出现了 TS2339 错误。

3.9、esModule配置问题

esModule 选项： 这个选项控制 Lodash 是否使用 ES6 模块导出方式。启用 esModule 时，Lodash 会尝试使用 ES6 模块系统的特性（如 export 和 import），而不是 CommonJS 的 module.exports。

Error: To support the 'esModule' option, the 'variable' option must be passed to avoid 'with' statementsin the compiled template to be strict mode compatible. Please see https://github.com/lodash/lodash/issues/3709#issuecomment-375898111.To enable CommonJS, please set the 'esModule' option to false.

在你的 Webpack 项目中使用 Node.js 时，是否启用 esModule 选项取决于你希望如何使用模块和打包方式。一般来说，esModule 和 CommonJS 都有不同的语法和模块导出方式，选择是否启用 esModule 取决于以下几个因素：

1. 使用 ES6 模块语法 (ESM)
   如果你在项目中使用的是 ES6 模块语法，比如 import 和 export，你可能会希望启用 esModule，因为这会确保 Lodash 或其他库按照 ES6 模块的标准进行导出和导入。
2. 使用 CommonJS 模块语法
   如果你在项目中主要使用 CommonJS 模块语法，比如使用 require() 和 module.exports，那么你应该考虑 禁用 esModule 选项，因为启用后可能会导致与 CommonJS 语法的兼容性问题。
3. Webpack 默认行为
   Webpack 默认会处理模块并将它们转换为兼容浏览器的格式，通常 Webpack 会根据你的代码和目标环境自动决定是否使用 CommonJS 或 ESM。大多数情况下，Webpack 会将模块转为兼容的格式（比如在浏览器中会使用 ESM 模块，在 Node.js 环境中则可以使用 CommonJS）。