node: --openssl-legacy-provider 不允许在 NODE_OPTIONS 中使用的解决方法

问题描述

当在 Ubuntu 20.04 或其它操作系统上运行 Node.js 命令时，可能会遇到以下错误信息：

node: --openssl-legacy-provider is not allowed in NODE_OPTIONS

这个问题通常出现在 Node.js 升级后（特别是从 v16 升级到 v18），或者在系统更新后。错误可能出现在运行 npm start、node -v 或其它 Node.js 相关命令时。

问题原因

这个错误的主要原因是 Node.js 版本与 OpenSSL 配置不兼容。从 Node.js v17 开始，OpenSSL 3.0 成为默认版本，它不再支持一些旧的加密算法。当环境变量 NODE_OPTIONS 包含 --openssl-legacy-provider 选项时，新版本的 Node.js 会拒绝执行。

解决方案

方法一：清除 NODE_OPTIONS 环境变量（推荐）

最常见的解决方法是清除或重置 NODE_OPTIONS 环境变量：

Linux/macOS

# 临时清除（当前终端会话有效）
unset NODE_OPTIONS

# 或设置为空值
export NODE_OPTIONS=""

Windows CMD

set NODE_OPTIONS=

PowerShell

$env:NODE_OPTIONS = ""

TIP

这是最简单且最推荐的解决方案，因为它不需要修改项目配置或降低安全性。

方法二：更新 Node.js 版本

如果您使用的是较旧的 Node.js 版本（如 v16 或更早），升级到更新的 LTS 版本可能会解决问题：

nvm install v18  # 或更新的 LTS 版本
nvm use v18

方法三：项目特定的 npm 配置

如果您的项目确实需要 --openssl-legacy-provider 选项，可以在项目根目录的 .npmrc 文件中配置：

node-options="--openssl-legacy-provider"

注意

这种方法会降低安全性，只有在确实需要支持旧版加密算法时才应使用。

方法四：修改 package.json 脚本

对于 React、Vue 或 React Native 项目，可以修改 package.json 中的启动脚本：

React/Vue 项目

"scripts": {
  "start": "cross-env NODE_OPTIONS= react-scripts start",
  // 其他脚本...
}

React Native 项目

"scripts": {
  "start": "export NODE_OPTIONS= && react-native start",
  // Windows 用户可使用：
  // "start": "set NODE_OPTIONS= && react-native start",
  // 其他脚本...
}

方法五：检查系统级 OpenSSL 配置（高级）

在 Linux 系统上，您可以编辑 OpenSSL 配置文件来启用传统提供商支持：

1. 打开 /etc/ssl/openssl.cnf 文件
2. 找到并取消注释以下行：

[provider_sect]
default = default_sect
legacy = legacy_sect

[default_sect]
activate = 1

[legacy_sect]
activate = 1

警告

修改系统级 OpenSSL 配置可能会影响系统安全性，请谨慎操作。

预防措施

1. 定期更新 Node.js：保持 Node.js 版本更新可以避免许多兼容性问题
2. 使用 .nvmrc 文件：在项目中包含 .nvmrc 文件指定 Node.js 版本
3. 检查环境变量：定期检查您的环境变量，确保没有设置不必要的 NODE_OPTIONS

总结

node: --openssl-legacy-provider is not allowed in NODE_OPTIONS 错误通常是由于 Node.js 版本升级或环境变量配置不当导致的。最简单的解决方法是清除 NODE_OPTIONS 环境变量。如果您的项目确实需要传统 OpenSSL 支持，可以考虑更新项目依赖或使用项目特定的配置。

INFO

大多数现代前端框架已经更新以兼容 OpenSSL 3.0，建议优先更新依赖而不是依赖传统提供商。