Node.js 18+ 版本项目启动报错：OpenSSL 3.0 兼容性问题解决方案

问题描述

在使用 Node.js 18+ 版本运行项目时，可能会遇到如下错误：

Error: error:0308010C:digital envelope routines::unsupported

这个错误通常出现在启动 Vue、React 等前端项目时，具体错误堆栈如下：

Error: error:0308010C:digital envelope routines::unsupported

    at new Hash (node:internal/crypto/hash:69:19)

    at Object.createHash (node:crypto:133:10)

    at module.exports (/node_modules/webpack/lib/util/createHash.js:135:53)

问题原因

这个问题的根本原因是 Node.js 18+ 版本默认使用了 OpenSSL 3.0，而一些旧的项目或依赖包可能还在使用旧版本的 OpenSSL 加密方法。在 OpenSSL 3.0 中，一些旧的加密方法被标记为不安全，默认情况下被禁用了。

解决方案

方案一：设置环境变量（推荐）

在启动项目时，添加 NODE_OPTIONS 环境变量来启用旧版本的 OpenSSL 提供程序：

# Linux/Mac

export NODE_OPTIONS=--openssl-legacy-provider

npm run serve



# Windows

set NODE_OPTIONS=--openssl-legacy-provider

npm run serve

方案二：降级 Node.js 版本

如果不想修改环境变量，可以考虑降级到 Node.js 16.x 版本，该版本仍然使用 OpenSSL 1.1.1。

方案三：更新项目依赖

长期来看，最好的解决方案是更新项目依赖到最新版本，特别是：

• webpack
• webpack-dev-server
• 其他使用加密相关的依赖包

最佳实践建议

1. 在项目文档中明确标注所需的 Node.js 版本
2. 定期更新项目依赖，特别是涉及到加密相关的包
3. 在 CI/CD 流程中明确指定 Node.js 版本
4. 考虑使用 .nvmrc 文件来管理 Node.js 版本

补充说明

这个问题在以下场景中比较常见：

• 使用 Vue CLI 创建的项目
• 使用 Create React App 创建的项目
• 使用较旧版本的 webpack 的项目

参考链接

• Node.js 官方文档 (opens new window)
• OpenSSL 3.0 迁移指南 (opens new window)
• Webpack 官方文档 (opens new window)

希望这篇博客能帮助到遇到类似问题的开发者。如果您有任何问题或补充，欢迎在评论区讨论。