解决 Node.js 中 “digital envelope routines::unsupported” 错误

在使用 Webpack 构建 Joplin 插件时，你可能会遇到 error:0308010C:digital envelope routines::unsupported 错误。这个错误看起来很复杂，但实际上有明确的原因和解决方案。

错误原因分析

这个错误发生在 Node.js v17+ 版本中，根源是：

• Node.js v17+ 升级到了 OpenSSL 3.0
• OpenSSL 3.0 移除了一些不安全的加密算法（如 MD4）
• 旧版本的 Webpack（如我们项目中使用的 4.46.0）仍在使用这些被移除的算法

当你运行 npm run dist 时，Webpack 尝试使用已被移除的加密算法，导致 Node.js 抛出此错误。

解决方案

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

这是最简单快捷的解决方案，通过环境变量强制 Node.js 使用旧的加密模式：

Windows 命令提示符：

set NODE_OPTIONS=--openssl-legacy-provider
npm run dist

Windows PowerShell：

$env:NODE_OPTIONS = "--openssl-legacy-provider"
npm run dist

Linux/macOS：

export NODE_OPTIONS=--openssl-legacy-provider
npm run dist

方案 2：降级 Node.js 版本

如果希望长期使用而不设置环境变量，可以降级 Node.js 到 v16.x 或更低版本：

1. 卸载当前的 Node.js v20.17.0
2. 从 Node.js 官网 下载并安装 v16.x LTS 版本
3. 重新运行 npm run dist

方案 3：升级 Webpack 及相关依赖

这是最彻底但也最复杂的解决方案：

1. 升级 Webpack 到 5.x 版本：

npm install webpack@5 --save-dev

2. 升级相关 loader 和插件：

npm install ts-loader@latest webpack-cli@latest --save-dev

3. 根据需要调整 Webpack 配置文件以适应新版本的 API 变化

# 查看项目局部版本
npx webpack -v# 查看全局版本（若全局安装）
webpack -v

为什么这些方案有效？

• 方案 1 通过 --openssl-legacy-provider 选项让 Node.js 启用旧的加密算法支持，兼容 Webpack 4 的需求
• 方案 2 使用仍支持旧加密算法的 Node.js 版本，从根本上避免了兼容性问题
• 方案 3 升级到支持 OpenSSL 3.0 的 Webpack 版本，彻底解决了兼容性问题

总结

对于 Joplin 插件开发这类可能依赖特定版本构建工具的场景，我推荐优先使用方案 1（设置环境变量），它既能解决问题，又不会影响项目的其他依赖和配置。

如果计划长期维护这个项目，那么方案 3（升级 Webpack）是更好的选择，可以避免未来可能出现的其他兼容性问题。