文档Experience Cloud KCS

AEM前端内部版本支持Node.js和npm版本并与其兼容

最近更新： 2026年7月7日

AEM前端模块（例如，具有React或Webpack的ui.frontend）需要与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管道构建会失败。
  • 不确定哪个npm版本与支持的Node.js版本捆绑在一起（例如，带有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. 如果尽管配置正确，但生成仍失败，请通过管道日志、pom.xml、package.json和Adobe环境变量列表与Cloud Manager支持部门联系。

适用于AEM 6.5 （Managed Services和内部部署）的

  1. 请注意，AEM 6.5没有官方的Node.js支持列表。 Node.js由客户管理，仅用于构建时工具，并与AEM运行时分离。
  2. 更新Node.js和npm时，请保持package.json和pom.xml一致，以便本地和CI构建保持一致（例如，将节点12.22.7升级到16.17.0并将npm 6.14.0升级到8.15.0）。
  3. 通过在本地和CI中运行node -v和npm -v来确认版本，并验证前端构建是否完成，且没有版本不匹配错误。
  4. 如果仍然存在混淆或生成问题，请联系Adobe支持并提供您的生成脚本详细信息、pom.xml和package.json。

相关阅读

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