ERR_OSSL_EVP_UNSUPPORTED 错误解决方案

问题描述

在使用 Node.js 17+ 版本运行 Next.js、React 或其他基于 webpack 的项目时，可能会遇到以下错误：

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:67:19)
    ...
  opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ],
  library: 'digital envelope routines',
  reason: 'unsupported',
  code: 'ERR_OSSL_EVP_UNSUPPORTED'

这个错误通常发生在使用 npm run dev 或类似命令启动开发服务器时。问题的根源在于 Node.js 17+ 版本中 OpenSSL 3.0 的加密算法兼容性问题。

解决方案

方法一：降级到 Node.js 16 LTS 版本（推荐）

最稳定的解决方案是使用 Node.js 的长期支持版本（LTS）：

bash

# 使用 nvm 切换 Node.js 版本
nvm install 16.13.0
nvm use 16.13.0

# 或者设置为默认版本
nvm alias default v16.13.0

TIP

Node.js 16 LTS 版本提供了更好的稳定性和兼容性，适合大多数生产环境。

方法二：使用环境变量临时解决方案

如果你需要临时使用 Node.js 17+ 版本，可以通过设置环境变量来解决问题：

bash

# 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 中直接配置：

json

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

WARNING

这种方法只是临时解决方案，建议尽快迁移到 Node.js 16 LTS 版本。

方法三：Docker 环境中的解决方案

如果你在使用 Docker，可以在 Dockerfile 中指定使用 Node.js 16 版本：

dockerfile

FROM node:16.13.0-alpine

# 其余配置保持不变
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

问题原因分析

这个错误是由于 Node.js 17+ 版本开始使用 OpenSSL 3.0，其中移除了一些旧的加密算法。而 webpack 4 和一些依赖的库仍然在使用这些被移除的算法，导致兼容性问题。

INFO

OpenSSL 3.0 是 OpenSSL 的一个主要版本更新，引入了新的提供者概念并移除了一些不安全的传统算法。

版本兼容性参考

Node.js 版本	OpenSSL 版本	是否受影响	推荐操作
≤ 16.x	OpenSSL 1.1.x	否	继续使用
≥ 17.x	OpenSSL 3.0	是	降级或使用兼容模式

总结

对于大多数开发者和项目，建议采用方法一：切换到 Node.js 16 LTS 版本。这是最稳定且无需额外配置的解决方案。

如果你需要临时使用 Node.js 17+ 版本，可以使用方法二的环境变量方案，但请注意这只是一个过渡方案。

DANGER

不建议在生产环境中使用 --openssl-legacy-provider 标志，因为它可能会降低安全性。

随着生态系统的更新，未来的 webpack 5 和相关工具版本将会原生支持 OpenSSL 3.0，届时这个问题将自然解决。

相关文章

ERR_OSSL_EVP_UNSUPPORTED 错误解决方案 ​

问题描述 ​

解决方案 ​

方法一：降级到 Node.js 16 LTS 版本（推荐） ​

方法二：使用环境变量临时解决方案 ​

方法三：Docker 环境中的解决方案 ​

问题原因分析 ​

版本兼容性参考 ​

总结 ​