解決 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）是更好的選擇，可以避免未來可能出現的其他兼容性問題。