theme: cyanosis

解决若依框架中 npm run dev 卡在 95% 的问题

在使用若依（RuoYi）框架进行项目开发时，许多开发者会遇到一个令人头疼的问题：运行 npm run dev 启动前端服务时，进度卡在 95%，最终抛出错误而无法继续。这篇文章将深入分析问题的原因，并提供高效的解决方案，为开发者提供清晰的指导。

问题背景

该问题通常出现在使用 Node.js 17 或更高版本的开发环境中。自 Node.js 17 起，Node.js 将默认集成 OpenSSL 3.0，而 OpenSSL 3.0 的加密算法支持策略发生了显著变化，某些过时的加密算法（例如 MD4）的支持被弱化或移除。这些变化对于依赖旧算法的项目来说是一次重要的兼容性挑战。若依框架的部分依赖可能直接或间接使用了这些算法，导致在运行 npm run dev 命令时出现兼容性问题。尤其是对前端构建工具的影响，可能使开发者误以为是项目本身的问题。

错误现象

执行 npm run dev 后，控制台输出会停滞在：

95% emitting …

随后抛出错误，提示与加密算法或构建工具相关的失败信息。这种现象极大程度上阻碍了开发者的工作进度，特别是在缺乏详细错误日志时，问题变得更加复杂。

问题分析

这一问题的根源在于项目的依赖项未完全兼容 OpenSSL 3.0。而 set NODE_OPTIONS=--openssl-legacy-provider 这一命令的作用是强制 Node.js 使用 OpenSSL 的旧版提供程序，从而恢复对旧加密算法的支持。这种支持能够临时解决由于加密算法变更导致的构建问题。

此外，项目的依赖项可能未及时更新，构建工具（如 Webpack、Babel）在处理这些依赖时受到影响，进一步加剧了问题的复杂性。

解决方案

临时解决方案

可以通过手动设置环境变量来快速解决问题：

Windows 系统：

打开命令提示符，执行以下命令：

set NODE_OPTIONS=--openssl-legacy-provider

npm run dev

macOS 或 Linux 系统：

打开终端，执行以下命令：

export NODE_OPTIONS=--openssl-legacy-provider

npm run dev

需要注意的是，这种设置方法仅对当前终端会话有效，关闭终端后需要重新设置。对于快速测试或短期开发任务，这是最简单的解决方法。

永久解决方案

为了避免每次都需要手动设置环境变量，可以将上述设置添加到 package.json 中的脚本部分。

打开项目根目录下的 package.json 文件。

找到 scripts 部分，修改 dev 脚本：

Windows 系统：

"scripts": {

"dev": "set NODE_OPTIONS=--openssl-legacy-provider && vue-cli-service serve"

}

macOS 或 Linux 系统：

"scripts": {

"dev": "export NODE_OPTIONS=--openssl-legacy-provider && vue-cli-service serve"

}

通过这种方式，执行 npm run dev 时会自动设置环境变量，从而简化开发过程。

替代方案

如果不希望修改环境变量，可以考虑降低 Node.js 的版本到 16.x 或更低版本。Node.js 16 是一个长期支持（LTS）版本，与旧版本的 OpenSSL 保持兼容，能够稳定运行现有的依赖项。

此外，还可以通过逐步检查和更新项目依赖项的方式解决问题。运行以下命令查看需要更新的依赖项：

npm outdated

逐步将老旧依赖更新至兼容版本，能从根本上避免类似问题。

注意事项

依赖更新： 长期来看，建议更新项目依赖，使其与最新版本的 Node.js 和 OpenSSL 兼容。依赖的及时更新不仅能避免构建问题，还能提高项目的安全性和性能。

版本兼容性： 如果项目需要长期维护，建议使用 LTS 版本的 Node.js，避免因频繁更新导致的兼容性问题。这对于团队协作和生产环境尤为重要。

未来变更： --openssl-legacy-provider 是一种过渡性的解决方案，可能会在未来版本中被移除。因此，尽快解决依赖项的兼容性问题至关重要。

开发环境隔离： 使用容器化工具（如 Docker）隔离开发环境，可以有效避免因 Node.js 或系统环境变化导致的问题，为团队提供统一的开发环境。

总结

通过设置 NODE_OPTIONS=--openssl-legacy-provider，可以快速解决若依框架中 npm run dev 卡在 95% 的问题。然而，为了保证项目的长期稳定性，开发者应优先考虑升级依赖项并使用 LTS 版本的 Node.js。此外，依赖管理和开发环境的标准化对于提升团队效率和项目质量具有重要意义。希望本文能帮助您快速定位问题并解决它，让您的开发过程更加顺畅高效。