node ---- 解决错误【Error: error:0308010C:digital envelope routines::unsupported】

news2025/4/17 14:19:17

1. 报错

在 Node.js 18.18.0 的版本中，遇到以下错误：

this[kHandle] = new _Hash(algorithm, xofLen);
                  ^
Error: error:0308010C:digital envelope routines::unsupported

这个错误通常发生在运行项目或构建时，尤其是在使用 Webpack、Vite 或其他构建工具时。

2. 报错截图

输入图片说明

3. 错误原因

该错误的根本原因是 Node.js 17+ 默认使用了 OpenSSL 3.0，而 OpenSSL 3.0 移除了对一些旧版加密算法（如 MD4 、 MD5 等）的支持。如果你的项目或依赖库中使用了这些旧版算法，就会触发此错误。

4. 解决方案一：临时解决方案：启用旧版 OpenSSL 提供程序

通过设置环境变量 NODE_OPTIONS ，可以启用旧版 OpenSSL 提供程序，从而解决兼容性问题。

4.1 Linux/MacOS

export NODE_OPTIONS=--openssl-legacy-provider

4.2 Windows

set NODE_OPTIONS=--openssl-legacy-provider

4.3 在 package.json 中设置

如果你希望在运行脚本时自动应用此设置，可以修改 package.json ：

"scripts": {
  "dev:h5:set": "SET NODE_OPTIONS=--openssl-legacy-provider && npm run build:h5 -- --watch",
  "dev:h5:export": "export NODE_OPTIONS=--openssl-legacy-provider && npm run build:h5 -- --watch"
}

5. 解决方案二：降级 Node.js 版本

如果你的项目对 Node.js 版本要求不高，可以降级到 Node.js 16 或更低版本，因为这些版本默认使用 OpenSSL 1.1.1，不会触发此错误。

使用 nvm 切换 Node.js 版本：

nvm install 16
nvm use 16

6. 解决方案三：更新项目依赖

检查项目中是否有依赖库使用了旧版加密算法，并尝试更新这些依赖库到最新版本。通常，新版本会修复与 OpenSSL 3.0 的兼容性问题。

7. 解决方案四：修改 Webpack 配置

如果你使用的是 Webpack，可以通过修改配置来避免使用旧版加密算法：

module.exports = {
  output: {
    hashFunction: 'sha256', // 使用 SHA-256 替代 MD5
  },
};

8. 注意事项

临时解决方案的风险： --openssl-legacy-provider 是一个临时解决方案，旧版 OpenSSL 提供程序可能存在安全风险，建议仅在开发环境中使用。
生产环境：在生产环境中，应尽量避免使用临时解决方案，而是通过更新依赖或降级 Node.js 版本来解决问题。
长期解决方案：建议尽快更新项目或依赖库，避免使用旧版加密算法。