Node.js

冒頭まとめ ERR_REQUIRE_ESMは、require()でESモジュールを読み込もうとして、その実行環境が読み込みを拒否したときに出ます。ESモジュール(ESM)は、主にimportとexportで読み書きする形式です。CommonJS(CJS)は、require()とmodule.exportsを使う形式です。 最初にエラーに出た読み込み先と読み込み元、実際に使われたNode.jsの版を確認します。自分のCommonJSコードなら、非同期のimport()に書き換える方法があります。依存パッケージ内部で起きているなら、呼び出しているパッケージの対応版も調べてください。 新しいNode.jsは同期的なESMをrequire()で読み込めます。ただし、更新だけで元の使い方が必ず通るわけではありません。戻り値の取り出し方と、依存先を含めたトップレベルのawaitの有無も確認します。 エラーのパスと実行環境を確認する 次は表示例です。パスは説明用で、文言や補足はNode.jsの版によって変わります。 Error [ERR_REQUIRE_ESM]: require() of ES Module /project/lib.mjs from /project/main.cjs not supported. lib.mjsが読み込もうとしたファイル、fromの後ろにあるmain.cjsが読み込み元です。両方のパスを確認すると、自分のコードと依存パッケージ内部のどちらを直す必要があるかを判断できます。 Node.js v22.12.0のエラー生成実装には、.mjsの場合、ESM構文を含む場合、近くのpackage.jsonの"type": "module"によってESMとして扱う場合に応じた補足があります。ただし、補足の種類だけで対処を固定せず、実際のコードと設定も確認します。 失敗した処理と同じターミナルやCIジョブで、次を実行してください。 node -v node -p "process.execPath" node -p "JSON.stringify({execArgv: process.execArgv, NODE_OPTIONS: process.env.NODE_OPTIONS})" 最後のコマンドは、その確認用プロセスの起動引数とNODE_OPTIONSを表示します。npmスクリプトやツールが別途渡す引数は、その実行設定も確認してください。Node.jsを更新したつもりでも、IDE、CI、コンテナでは別の実行ファイルを使っている場合があります。 Node.jsの版による違いを切り分ける 公式の変更履歴では、同期ESMのrequire()対応はNode.js 20.17.0と22.0.0に追加されました。当初は--experimental-require-moduleで有効にする機能でした。 系列・版 同期ESMをrequire()する機能 Node.js 18系 この機能に未対応 20.17.0〜20.18.x 実験的フラグで有効化 20.19.0以降の20系 既定で有効 22.0.0〜22.11.x 実験的フラグで有効化 22.12.0以降の22系 既定で有効 23.0.0以降の系列 既定で有効。無効化設定にも注意 これは機能が導入された境界の表です。古い系列への更新を推奨する表ではありません。更新先は、Node.js公式のサポート状況とプロジェクトの要件を確認して、サポート中のLTS(長期サポート版)から選びます。2026年10月8日の確認では22系と24系がLTS、20系はサポート終了です。 機能を無効化している場合、新しい版でもERR_REQUIRE_ESMが出ることがあります。起動設定やNODE_OPTIONSの--no-experimental-require-moduleなどを確認します。フラグの名称や利用可否は、使用中の版の文書に合わせてください。 公式エラー文書がこのエラーを非推奨としている理由は、同期ESMをrequire()で読み込めるようになったためです。非推奨という表示は、発生頻度や件数の根拠ではありません。 CommonJSを残してimport()に書き換える CommonJSのままESMを読み込むには、import()を使えます。ESMの公式文書も、CommonJS内からESMを読み込む方法として説明しています。 次は外部パッケージを使わない例です。2つのファイルを同じディレクトリへ保存します。 // lib.mjs export default function greet(name) { return `Hello, ${name}`; } export const label = 'example'; // main.cjs async function main() { const { default: greet, label } = await import('./lib.mjs'); console.log(greet(label)); } main().catch((error) => { console.error(error); process.exitCode = 1; }); node main.cjs import()はPromiseを返すため、読み込み完了を待ってから使います。CommonJSのファイル直下にそのままawait import(...)を書かず、この例のようにasync関数内へ入れます。呼び出し側も、結果が非同期で返ることに合わせる必要があります。 ...