看完本文，保证你在系统Node.js升级过程中一帆风顺！

node升级问题

• 本人HB实习，最近的任务是把web端的node从10升级到16版本，三周期间遇到各种问题，几乎把该踩的坑都踩过了。记录下来，希望给后来的小伙伴带来一些帮助。

目标

• 升级至node16.15.0

• 执行npm run build

• 执行npm run start

• 页面成功显示

路线

基本路线图：node升级 ----> 依赖包适配 ----> python环境适配 ----> 依赖包适配 ----> gulp升级适配 ----> 依赖包适配 ----> babel升级适配 ----> 依赖包适配 ----> webpack升级适配 ----> xxx.loader适配 ----> 依赖包适配

问题汇总

问题一

• ReferenceError: primordials is not defined

原因

• 当NodeJS版本是12.0.0以上 和 gulp版本是3.9.x以下时，此两个版本之间存在冲突。

  gulp:4.0.2

  CLI:2.3.0

解决：

• 方法一：node降级(舍去)

• 方法二：升级gulp -> sudo npm install -g gulp

• 方法三：项目根目录新建npm-shrinkwrap.json，

  • 然后重新执行npm install，这时候再去执行gulp相关操作就不会报错了。注意：这个文件在执行过一次npm install以后，就失效了，下次再执行就没有效果了。

  • 写入：
        {
           "dependencies": {
               "graceful-fs": {
                   "version": "4.2.2"
                }
           }
         }
    

问题二

• ERESOLVE unable to resolve dependency tree(无法解析依赖关系树)

原因

• 因为本地的npm版本太高了

解决

• sudo npm i --legacy-peer-deps

问题三

• Module build failed: Error: Cannot find module 'node-sass' 原因
• node版本不匹配的问题

解决

• sudo npm uninstall --save node-sass
• npm install --save node-sass

问题四

• ERESOLVE could not resolve

原因

• package.json里面包的版本发生了变化，或者新添的包与原本的不匹配,使用npm install 无法下载相应版本的包

解决

• 1. 安装rimraf: cnpm(或者npm) install rimraf
• 1. 删除node_modules文件夹：rimraf node_modules
• 1. 清空缓存：npm cache clean --force
• 1. 重新安装淘宝镜像： npm install -g cnpm --registry=regisry.npm.taobao.org
• 1. 再次执行命令进行相关包的安装： cnpm i

问题五

• npm install 是显示需要python环境并且版本>3.6.0

原因

• (mac自带的是2.7.x)

解决

• 安装python3.x( > 3.6.0)
• 配置环境变量

清除npm缓存

• sudo npm cache clean --force

问题六

• code ERESOLVE
• npm ERR! ERESOLVE unable to resolve dependency tree
• npm ERR!
• npm ERR! While resolving:xxx
• npm ERR! Found: eslint@8.0.0
• node_modules/eslint
• npm ERR! dev eslint@"8.0.0" from the root project
• npm ERR! Could not resolve dependency:
• npm ERR! peer eslint@"4.19.1" from dev-hook-utils@1.1.5
• node_modules/dev-hook-utils
• npm ERR! dev-hook-utils@"^1.1.5" from the root project

原因：

• 上游依赖冲突

解决

• 无脑改成peer后面的版本
• 这里要非常慎重，各种版本依赖，还有可能闭环，呜呜呜～～～～

问题七

• npm ERR! code 1
• npm ERR! .....
• npm ERR! command failed

原因

• npm版本冲突

解决

• ...
• 1.更换至node版本对应的npm版本(nodejs.org/zh-cn/downl…)

问题八

• npm ERR! gyp: No Xcode or CLT version detected!

原因

• 缺少了XCODE的CLI（command-line tools ）工具

解决：删了重装

• sudo rm -rf $(xcode-select -p)
• sudo rm -rf /Library/Developer/CommandLineTools
• sudo xcode-select --install

问题九

• AssertionError [ERR_ASSERTION]: Task never defined: clean

原因

• Node.js v12+ 不支持 Gulp v3。

解决：

• v4的语法有些许改动

原来：
gulp.task("less",()) => {
};
​
gulp.task("default",["webpack","clean"]);
​
--------------------------
​
修改为：
gulp.task("less",gulp.series(()) => {
});
​
gulp.task("default",gulp.series("webpack","clean"));

问题十

• AssertionError [ERR_ASSERTION]: Task never defined: clean 原因：
• gulpfile.js是从上到下加载

解决：

• 把clean函数放在前面

问题十一

• [14:18:15] The following tasks did not complete: build,
• [14:18:15] Did you forget to signal async completion?

原因：

• gulp4都是异步函数，没有同步函数了。
• 每个 gulp 任务（task）都是一个异步的 JavaScript 函数，此函数是一个可以接收 callback 作为参数的函数，或者是一个返回 stream、promise、event emitter、child process 或 observable类型值的函数

解决：

• 官方发布方法

gulp.task('default',done =>){
  done();
}

问题十二

• npm ERR! gyp ERR! cwd /Users/xxx/node_modules/node-sass

原因：

• 版本不匹配

解决

• 把用不到的库删除

问题十三

• ValidationError: Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.

  • options has an unknown property 'quiet'. These properties are valid: object { mimeTypes?, writeToDisk?, methods?, headers?, publicPath?, stats?, serverSideRender?, outputFileSystem?, index? }

原因： webpack 2 => 4

解决： 注释掉 quiet=true

---

问题十四

• Module build failed (from ./node_modules/babel-loader/lib/index.js): Error: Plugin/Preset files are not allowed to export objects, only functions. In /Users/xxx/node_modules/babel-preset-stage-2/lib/index.js

原因：

• bable版本不匹配

解决

• bable-x 全部最新版本

npm install -D babel-loader @babel/core @babel/preset-env @babel/preset-react webpack

---

问题十五

• TypeError: Cannot read properties of undefined (reading 'vue')

原因：

• vue-loader版本

解决

• 升至15.x

---

问题十六

• Path variable [contenthash] not implemented in this context: static/css/[name].[contenthash].css] 原因：
• webPack 升级到 4.x导致
• 在之前版本中我们使用extract-text-webpack-plugin来提取CSS文件，不过在webpack 4.x中则应该使用mini-css-extract-plugin来提取CSS到单独文件中

解决：

• contenthash 改成 md5:contenthash:hex:20

webpack.xxx.conf.js中
----------------------
const utils = require('./utils')
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
​
module.exports = {
   //...
   new MiniCssExtractPlugin({
       filename: utils.assetsPath('css/[name].[contenthash:7].css')
  })
}
--------------------------
webpack.base.conf.js
--------------------
 test: /.(css|less)$/,
       use: [
         {
           loader:MiniCssExtractPlugin.loader,
      }

问题十七

• Module build failed: Unknown word

原因：

• 冲突

解决：

• 多余的注释掉

---

问题十八

• Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.

原因：

• 因为 sass 新版本目前弃用“/”的用法，sass自定义element theme时会报warnning

解决：

• npm install -g sass-migrator
• 进入项目node_modules文件
• 执行sass-migrator division */ .scss

问题十九

• Warning: Accessing non-existent property 'which' of module exports inside circular dependency

原因

• shelljs版本不兼容

解决

• 可切换node至v10.版本
• 升级shelljs到 v0.8.4 即可解决;升级shelljs：npm install shelljs@0.8.4 --save (然后在npm rebuild node-sass)

问题二十

• Module parse failed: Unexpected token (915:0)

原因

• webpack默认是不能处理vue文件，所以只能我们自己添加一些额外的插件进行处理它。

解决：

• npm install vue-loader vue-template-compiler --save-dev
• 在webpack.conf.js配置

 module:{
      rules:{
              test:"/.vue$/",
              use:{
                      loader:"vue-loader"}
              }
}

问题二十一

• ValidationError: Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.

原因：

• css-loader版本只要 > 1.0.0,minimize失效

解决：

• 删除minimize

问题二十二

• DeprecationWarning: Tapable.plugin is deprecated. Use new API on .hooks instead (Use node --trace-deprecation ... to show where the warning was created)

原因：

• extract-text-webpack-plugin不兼容webpack4.x版本

解决：

• npm install extract-text-webpack-plugin@next

问题二十三

• CssSyntaxError:xxx: Unknown word

原因：

• css-loader问题

问题二十四

• RangeError: Invalid string length

原因：

• vue-loader问题

问题二十五

• /deep/编译错误

原因

• /deep/ 已弃用

解决

• 修改为 ::v-deep

问题二十六

• The 'mode' option has not been set, webpack will fallback to 'production' for this value.

原因：

• 升级至webpack4后未指定mode

解决：

• webpack.base.conf,js中：

module.exports = {
  ...
      mode: 'development',
  ...
}

问题二十七

• TypeError: MiniCssExtractPlugin.extract is not a function

原因：

• webpack(2-->4),[extract-text-webpack-plugin]不再被支持，需要替换为[mini-css-extract-plugin],对应代码也需更改。

解决

  return ExtractTextPlugin.extract({
     use: loaders,
     fallback: 'vue-style-loader'
    })
-----修改为以下---------
   return [MiniCssExtractPlugin.loader].concat(loaders)

问题二十八

• Error: webpack.optimize.UglifyJsPlugin has been removed, please use config.optimization.minimize instead.

原因：

• webpack.optimize.UglifyJsPlugin在webpack4.x已弃用

解决

• webpack.conf.js在output同级目录下新增optimization

- new webpack.optimize.UglifyJsPlugin({...})
-----------------------------
+
optimization: {
   minimizer:[new UglifyJsPlugin()
   }

问题二十九

• Error: webpack.optimize.CommonsChunkPlugin has been removed, please use config.optimization.splitChunks instead

原因：

• webpack4不支持webpack.optimize.CommonsChunkPlugin
• webpack4删除了CommonsChunkPlugin插件，需要使用内置API optimization.splitChunks 和 optimization.runtimeChunk替代

解决

- new webpack.optimize.CommonsChunkPlugin({...})
--------------------------------
+
optimization: {
  runtimeChunk: {
     name: 'manifest',
   },
   splitChunks: {
          chunks: 'async',
          minSize: 30000,
          minChunks: 1,
          maxAsyncRequests: 5,
          maxInitialRequests: 3,
          automaticNameDelimiter: '~',
          name: true,
          cacheGroups: {
            vendors: {
              test: /[\\/]node_modules[\\/]/,
          }
      }
  }
}

问题三十

• TypeError: fsevents.watch is not a function

原因

• 版本问题

解决

• 解决办法：npm install watchman
• 还是不行：brew install gcc

问题三十一

• dev-hook-utils > pre-commit
• Start to lint staged files Start eslintError: Failed to load config "eslint-config-airbnb/base" to extend from.

原因：

• 依赖缺失

解决：

• npm i eslint-config-airbnb@[版本号] eslint-plugin-import@[版本号] -D
• 注：二者版本有依赖，记得要版本兼容否则报错

写在最后

• 说实话，一路走来，遇到各式各样的问题，好多次想的：把问题抛出去得了，反正我一个实习生搞不定这么大的问题。但是三个礼拜下来，终于是成功的build、start、显示成功了。收获满满！

• 星光不负赶路人，时光不负有心人！！！

• 共勉！！！