Node.jsで「Error: error:0308010C:digital envelope routines::unsupported」(ERR_OSSL_EVP_UNSUPPORTED)を修正する方法

何が起きているかビルドを実行したか、開発サーバーを起動したところ、次のエラーが表示されました：

Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:67:19)
    at Object.createHash (node:crypto:130:10)
    ...
ERR_OSSL_EVP_UNSUPPORTED

Node.js 17以降はOpenSSL 3を同梱しています。問題は、プロジェクトがいまだに古いツール — webpack 4、react-scripts v4、あるいはOpenSSL 3で廃止された暗号化APIを呼び出すパッケージ — に依存していることです。コードは変わっていません。ランタイムが変わったのです。 具体的には、OpenSSL 3がMD4ベースのハッシュのサポートを削除しました。これはまさにwebpack 4がチャンクハッシュ生成のために内部で使用していたものです。これが問題の核心です。

環境の確認まず以下の2つのコマンドを実行してください：

node -v
openssl version

Node.js 17以降とOpenSSL 3.xの組み合わせが原因です。スタックトレースも手がかりになります — ほぼ必ずnode:internal/crypto/hashや、数フレーム深いところに埋まったwebpackモジュールを指しています。

解決策### オプション1：NODE_OPTIONSを設定する（即効性あり、CI/ローカル開発向け）今すぐ問題を解消するには、環境変数1つだけで十分です：

# Linux / macOS
export NODE_OPTIONS=--openssl-legacy-provider
npm start

# Windows (コマンドプロンプト)
set NODE_OPTIONS=--openssl-legacy-provider
npm start

# Windows (PowerShell)
$env:NODE_OPTIONS="--openssl-legacy-provider"
npm start

毎回設定するのが面倒ですか？package.jsonに組み込んでおけば、チーム全員が自動的に適用されます：

{
  "scripts": {
    "start": "NODE_OPTIONS=--openssl-legacy-provider react-scripts start",
    "build": "NODE_OPTIONS=--openssl-legacy-provider react-scripts build"
  }
}

注意点：これは非推奨の動作を再有効化するものです。動作はしますが、あくまで一時的な橋渡しであり、最終的な解決策ではありません。根本的な対応に向けた時間を確保してください。

オプション2：react-scriptsをアップグレードする（Create React Appプロジェクト向け）まだreact-scripts v4を使っていますか？バージョン5ではwebpack 5に切り替わっており、OpenSSL 3をワークアラウンドなしで処理できます：

npm install react-scripts@latest

アップグレード後はNODE_OPTIONSのハックを削除し、フルビルドを実行して確認してください。react-scripts 5はNode.js 18以降でそのまま動作します — フラグは不要です。

オプション3：webpackをアップグレードする（カスタムwebpackセットアップ向け）webpackを自分で管理していますか？v4からv5へ移行しましょう：

npm install webpack@latest webpack-cli@latest

webpack 5はOpenSSL 3と完全に互換性のある別のアルゴリズムを使用してチャンクハッシュを生成します。ただし、アップグレードには破壊的変更が含まれています — 作業前に公式移行ガイドに目を通しておきましょう。

オプション4：Node.jsをダウングレードする（最終手段）今すぐ依存関係を変更できませんか？OpenSSL 1.1.1を同梱するNode.js 16に固定しましょう：

# nvmを使用する場合
nvm install 16
nvm use 16

# デフォルトとして設定
nvm alias default 16

チーム全員が同じバージョンを使うよう、.nvmrcファイルをコミットしましょう：

echo "16" > .nvmrc

注意点：Node.js 16は2023年9月にサポート終了を迎えています。これは時間を稼ぐ手段であり、長期的な解決策ではありません。

修正の確認ビルドまたは開発サーバーを実行してください：

npm start
# または
npm run build

出力にERR_OSSL_EVP_UNSUPPORTEDが表示されなければ完了です。CIを使用している場合は、環境変数がCI環境にも実際に設定されているか再確認してください — 修正が見落とされる最も多い場所です。 Nodeの暗号処理を直接テストしたいですか？このワンライナーを試してください：

node -e "require('crypto').createHash('md4').update('test').digest('hex')"

レガシーフラグなしのNode.js 17以降ではエラーになります。--openssl-legacy-providerを付けるとクリーンに実行されます。完全にアップグレードされたスタック（webpack 5 + Node 18以降）では、md4自体が不要になり — 問題は自然と解消されます。

どの修正を選ぶか- 短期対応 / CI向け：NODE_OPTIONS=--openssl-legacy-providerを設定する- CRAプロジェクト：react-scripts@5にアップグレードする- カスタムwebpack：webpack 5にアップグレードする- 依存関係を変更できない場合：一時的にNode.jsをv16に固定する## 次回から回避するにはこのエラーは、誰かがNode.jsをグローバルにアップグレードした際や、CIがランナーイメージをサイレントに更新した際に、ビルドツールが対応できるかどうかを確認せずに発生します。これを防ぐ3つの習慣があります：

• .nvmrcとpackage.jsonのenginesフィールドにNode.jsのバージョンを固定してください。バージョンが明示されていなければ、予期しない問題が起きるのは時間の問題です。- Node.jsのメジャーバージョンを上げる前に、ビルドツールに互換性のあるリリースが存在するか確認してください。5分の確認で、パイプラインの破損を防げます。- 2024年を過ぎても--openssl-legacy-providerを使い続けているなら、ビルドツールのアップグレードをバックログに追加してください。このフラグがすぐになくなるわけではありませんが、未完了の作業があることを示すサインです。