Node.js 17 ERR_OSSL_EVP_UNSUPPORTED 错误解决方案

问题描述

当使用 Node.js 17+ 版本（如 v17.0.1）运行 Gatsby、React、Vue.js 或 Angular 等前端项目时，可能会遇到以下错误：

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 17+ 开始使用 OpenSSL 3.0，它默认不再支持某些旧的加密算法和密钥大小。

解决方案

1. 最佳解决方案：更新 Webpack

这是最推荐的长期解决方案，因为多数前端框架都依赖 Webpack。

版本要求

• Webpack 4：升级到 v4.47.0 或更高版本
• Webpack 5：升级到 v5.61.0 或更高版本

升级命令：

npm update webpack
# 或者
yarn upgrade webpack

Webpack 团队通过使用 WASM 实现的 md4 算法替代 Node.js 内置实现，从根本上解决了这个问题。

2. 临时解决方案：使用 OpenSSL 传统提供程序

如果无法立即升级 Webpack，可以使用 Node.js 提供的临时解决方案：

通过环境变量设置

# Unix/Linux/macOS
export NODE_OPTIONS=--openssl-legacy-provider

# Windows (命令提示符)
set NODE_OPTIONS=--openssl-legacy-provider

# Windows (PowerShell)
$env:NODE_OPTIONS="--openssl-legacy-provider"

在 package.json 中配置

React

{
  "scripts": {
    "start": "NODE_OPTIONS=--openssl-legacy-provider react-scripts start",
    "build": "NODE_OPTIONS=--openssl-legacy-provider react-scripts build"
  }
}

Vue.js

{
  "scripts": {
    "serve": "NODE_OPTIONS=--openssl-legacy-provider vue-cli-service serve",
    "build": "NODE_OPTIONS=--openssl-legacy-provider vue-cli-service build"
  }
}

Gatsby

{
  "scripts": {
    "develop": "NODE_OPTIONS=--openssl-legacy-provider gatsby develop",
    "build": "NODE_OPTIONS=--openssl-legacy-provider gatsby build"
  }
}

Windows 通用

{
  "scripts": {
    "start": "set NODE_OPTIONS=--openssl-legacy-provider && react-scripts start",
    "build": "set NODE_OPTIONS=--openssl-legacy-provider && react-scripts build"
  }
}

使用 cross-env（跨平台解决方案）

npm install --save-dev cross-env

然后在 package.json 中：

{
  "scripts": {
    "build": "cross-env NODE_OPTIONS=--openssl-legacy-provider vue-cli-service build"
  }
}

3. 降级 Node.js 版本

如果上述方法都不适用，可以考虑暂时降级到 Node.js 16 LTS 版本：

注意

这应该是最后的选择，因为降级可能会影响其他功能的兼容性。

使用 nvm（Node Version Manager）管理多版本：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装并使用 Node.js 16
nvm install 16
nvm use 16

对于 Windows 用户，可以使用 nvm-windows。

根本原因分析

Node.js 17+ 开始使用 OpenSSL 3.0，它加强了安全限制，不再默认支持某些旧的加密算法。许多前端构建工具（如 Webpack）使用 md4 算法进行哈希计算，这在 OpenSSL 3.0 中已被移至传统提供程序。

技术细节

Webpack 使用 md4 算法生成文件哈希，而 Node.js 17+ 的 OpenSSL 3.0 默认不再支持该算法。Webpack 的解决方案是实现了自己的 md4 WASM 版本，不依赖 OpenSSL。

推荐方案

1. 首选：升级 Webpack 到已修复的版本（v4.47.0+ 或 v5.61.0+）
2. 临时方案：使用 --openssl-legacy-provider 标志
3. 最后选择：降级到 Node.js 16 LTS 版本

长期来看，升级相关依赖是最安全、最稳定的解决方案，因为使用传统提供程序只是临时绕过安全限制的方法。

验证解决方案

修复后，可以通过以下命令验证是否正常工作：

# 对于 React 项目
npm run build

# 对于 Vue.js 项目
npm run serve

# 对于 Gatsby 项目
npm run develop

如果不再出现 ERR_OSSL_EVP_UNSUPPORTED 错误，说明解决方案已生效。