Vue构建错误ERR_OSSL_EVP_UNSUPPORTED解决指南

2025-03-13 03:28:17

Vue 项目构建失败：ERR_OSSL_EVP_UNSUPPORTED 错误全解析

最近，一些朋友在构建生产环境的 Vue 项目时遇到了一个挺头疼的问题：控制台报错 ERR_OSSL_EVP_UNSUPPORTED。别慌，这篇文章帮你搞定它。

问题现象

构建 Vue 项目时（比如使用 npm run build 或者 yarn build），构建过程突然中断，并显示类似下面的错误信息：

Error: digital envelope routines::unsupported

opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ],
library: 'digital envelope routines',
reason: 'unsupported',
code: 'ERR_OSSL_EVP_UNSUPPORTED'

问题原因

这个问题的根源在于 Node.js v17 及更高版本中使用的 OpenSSL 版本。Node.js v17 开始默认使用 OpenSSL 3.0，而 OpenSSL 3.0 对一些旧的或不安全的加密算法进行了更严格的限制，默认不再支持。如果你的项目或者项目依赖的某个库，还在使用这些被弃用的算法（比如 MD4），就会触发这个错误。

更具体的说, 某些webpack版本与Openssl 3.0 不兼容。许多 Webpack 配置默认依赖 MD4 进行哈希。

解决方案

既然知道了原因，解决起来就有的放矢了。下面提供几种可行的解决方案：

1. 降级 Node.js 版本（不推荐）

最简单粗暴的方法，就是把 Node.js 版本降级到 v16 或更低版本。这样可以暂时避开 OpenSSL 3.0 的问题。

操作步骤：

卸载当前 Node.js 版本。
安装 Node.js v16 (推荐 LTS 版本)。可以使用 nvm (Node Version Manager) 这样的工具，更方便地管理多个 Node.js 版本。
重新构建项目。

缺点：

这只是权宜之计，治标不治本。新版本的 Node.js 通常有性能提升和安全修复，长期来看，还是应该升级的。
可能导致其他依赖出现兼容性问题。

2. 启用 OpenSSL Legacy Provider

Node.js 提供了 --openssl-legacy-provider 选项，可以强制启用旧版本的 OpenSSL 提供程序，从而兼容那些依赖旧算法的项目。

操作步骤：

修改 package.json:

在 package.json 文件的 scripts 部分，修改你的构建命令，加入 --openssl-legacy-provider 选项。

"scripts": {
    "build": "node --openssl-legacy-provider node_modules/.bin/vue-cli-service build",
     // 其他命令...
}

或者如果用的是webpack

"scripts": {
"build": "webpack --openssl-legacy-provider",
 // 其他命令...
 }

临时设置环境变量 (仅对当前终端窗口有效)：
如果你不想修改项目配置文件，可以临时设置环境变量 NODE_OPTIONS：

Linux / macOS:
```
export NODE_OPTIONS=--openssl-legacy-provider
npm run build
```
Windows (CMD):
```
set NODE_OPTIONS=--openssl-legacy-provider
npm run build
```

Windows (PowerShell):

$env:NODE_OPTIONS="--openssl-legacy-provider"
npm run build

3.升级依赖（推荐）

最佳方式，找到引发问题的具体依赖，然后升级到最新版本。

原理：

许多较新版本的依赖库，已经解决了与 OpenSSL 3.0 的兼容性问题。升级这些依赖，可以从根本上解决问题，同时也能享受新版本带来的好处。

操作步骤：

锁定问题依赖 . 可以通过 npm ls md4 或相似命令检查是哪个依赖库还在用过时的算法。
查看依赖官方文档 。查看是否已有新版修复了此问题.
更新依赖:
使用 npm update <package-name> 或者 yarn upgrade <package-name> 更新对应的包。
彻底检查 . 依赖更新完毕后,最好删除 node_modules 文件夹和 package-lock.json (或 yarn.lock), 之后 npm install 或 yarn install 重新安装所有依赖。

4. 修改 Webpack 配置（针对 Webpack 项目）

如果你的项目使用了 Webpack，并且确认是 Webpack 的哈希算法导致的问题，可以尝试修改 Webpack 配置，使用其他哈希算法。

操作步骤：
在项目的 Webpack 配置文件（通常是 webpack.config.js 或者 vue.config.js）中，找到 output 配置项，修改 hashFunction 属性。

// webpack.config.js / vue.config.js
module.exports = {
    // ... 其他配置
    output: {
        // ... 其他输出配置
        hashFunction: 'xxhash64', // 使用 xxhash64 算法
        // 或者使用sha256, sha384, sha512等更现代的算法
        // hashFunction: 'sha256'
    },
    // ...其他配置
};

解释: