ドキュメントExperience Cloud KCS

Node.jsおよびnpm バージョンのサポートとAEM フロントエンドビルドの互換性

最終更新日： 2026年7月7日

AEM フロントエンドモジュール（ui.frontendとReactまたはWebpackなど）には、AEM ビルド環境に対応したNode.js バージョンが必要です。サポートされていないバージョンまたは不一致のバージョンを使用すると、アップグレード時にCloud Manager パイプラインのビルドに失敗または不確かさが生じます。 この問題を修正するには、デプロイメントモデルを特定し、ターゲット Node.jsおよびnpm バージョンがサポートされていることを確認し、パイプライン設定で正しいバージョンを設定します。

説明 description

環境

  • Adobe Experience Manager as a Cloud Service
  • AEM Managed Services（AEM 6.5）
  • Adobe Experience Manager 6.5 （オンプレミス）

問題/症状

  • サポートされていないNode.js バージョン（サポートが追加される前にNode 20を使用するなど）を使用すると、Cloud Manager パイプラインのビルドが失敗します。
  • サポートされているNode.js バージョンにバンドルされているnpm バージョン（例：Node 18のnpm 10.8.2、Node 23.11.1のnpm 9.6.7）の不確実性。

根本原因

AEMのデプロイメントモデルによって、Node.jsの扱いが異なります。 AEM as a Cloud Serviceでは、Node.jsは、検証済みのバージョンを含むCloud Manager ビルドコンテナの一部です。 AEM 6.5 Managed Servicesまたはオンプレミスでは、Node.jsは管理するビルド時の依存関係であり、正式なサポートマトリックスは存在しません。 Cloud Managerでまだリリースされていないバージョンや、一致しないnpm バージョンを使用しようとすると、ビルドの互換性が失われる可能性があります。

再現手順

  1. デプロイメントモデルの特定：AEM as a Cloud Service、AEM 6.5 Managed Services、またはAEM 6.5 オンプレミス。
  2. AEM as a Cloud Serviceの場合、パイプラインのビルドステップでnode -vとnpm -vを実行し、ビルドログで印刷されたバージョンを確認します。
  3. ターゲットのNode.jsのバージョンを、公式にサポートされているバージョンリストと比較します。

解決策 resolution

この問題を解決するには、AEM デプロイメントモデルを特定し、次の手順に従います。

AEM as a Cloud Service用

  1. ターゲット Node.js バージョンがサポートされていることを確認します。 公式ドキュメントによると、サポートされているメジャーバージョンは12、14、16、18、20、22、23です。 Experience Leagueでサポートされているリストに対してクロスチェックします。
  2. Node.js バージョンにバンドルされているnpm バージョンを確認します。 Cloud Manager パイプラインのビルドステップでnode -vとnpm -vを実行し、ログを確認します（例：Node 18 バンドル npm 10.8.2、Node 23.11.1 バンドル npm 9.6.7）。 npmがそのバージョンに対して404を報告する場合、これはパブリックレジストリの違いを反映するので、実際のバンドルバージョンを確認してください。
  3. パイプラインでNode.js バージョンを設定します。 Cloud Managerで、Environments > Configuration > Environment Variablesに移動し、CM_CUSTOM_VAR_NODE_VERSION （または該当する場合はNODE_VERSION）を設定します。 パイプラインを再実行し、ログでノードバージョンを確認して、pom.xmlまたはビルドスクリプトで競合するバージョンが定義されていないことを確認します。
  4. フルスタックパイプラインの場合は、NODE_VERSIONを20に設定してNode.js 20を使用し、プロジェクトの依存関係をNode 20に互換性があるかどうかを検証します。
  5. 文書化されたサポートが存在する場合にのみ、Node.js 22または23を使用します。 フロントエンドのビルドに失敗した場合は、ノード 18または20に戻して、依存関係の互換性をテストします。
  6. 新しいNode.js バージョンでビルドをテストし、フロントエンドのリグレッションがないことを確認することで、サードパーティの依存関係の互換性を検証します。 Adobeでは互換性の詳細を提供できないため、ベンダー固有の問題については、サードパーティベンダーに直接お問い合わせください。
  7. ビルドログでnode -vとnpm -vを実行し、完全なパイプライン実行をトリガーして、バージョン不一致エラーなしでui.frontendのビルドが成功したことを確認して、修正を確認します。
  8. 正しい設定にもかかわらずビルドが失敗する場合は、Adobe サポートにパイプラインログ、pom.xml、package.json、およびCloud Manager環境変数リストを問い合わせます。

AEM 6.5 （Managed Servicesおよびオンプレミス）の場合

  1. AEM 6.5の正式なNode.js サポートマトリックスはありません。 Node.jsは顧客管理で、ビルド時のツールにのみ使用され、AEM ランタイムから切り離されます。
  2. Node.jsとnpmを更新する場合は、ローカルおよびCI ビルドが一致するようにpackage.jsonとpom.xmlの一貫性を維持します（例えば、Node 12.22.7を16.17.0に、npm 6.14.0を8.15.0にアップグレードします）。
  3. node -vとnpm -vをローカルおよびCIで実行してバージョンを確認し、バージョンの不一致エラーなしでフロントエンドのビルドが完了することを確認します。
  4. 混乱またはビルドの問題が残っている場合は、Adobe サポートに問い合わせて、ビルドスクリプトの詳細、pom.xmlおよびpackage.jsonを確認してください。

関連トピックス

recommendation-more-help
experience-cloud-kcs-help-kbarticles