部署Flowise AI到SAP BTP Cloud Foundry时遇NPM依赖冲突问题

部署场景 #

• 目标：将Flowise AI部署至SAP BTP Cloud Foundry环境
• 源码：使用官方Flowise AI仓库代码

本地环境与构建情况 #

本地可正常构建运行，环境参数：

• Node.js版本：18.20.3、18.20.4、20.15.1、20.16.0、22.7.0、22.8.0
• npm版本：10.7.0

本地构建命令：

commands:
  - "npm install -g pnpm"
  - "pnpm install"
  - "pnpm run build"

BTP Cloud Foundry部署配置 #

使用mta.yaml作为部署描述文件，内容如下：

_schema-version: "3.1"
ID: flowise
version: 0.0.1
description: Flowise HTML5 Application
parameters:
  keep-existing-routes: true
modules:
  - name: flowise
    type: html5
    path: Flowise 
    parameters:
      disk-quota: 1024M
      memory: 1024M
      buildpack: nodejs_buildpack
      stack: cflinuxfs4
      instances: 1
    build-parameters:
      builder: custom
      commands:
        - "npm install -g pnpm"
        - "pnpm install"
        - "pnpm run build"

部署错误信息 #

.mtar文件可成功构建，但部署至BTP Cloud Foundry时应用构建失败，错误核心信息：

BuildPackCompileFailed
Error Details:
The root cause of the failure appears to be a dependency issue. Here is a snippet of the error captured during the deployment process:

npm ERR! Found: @mendable/firecrawl-js@0.0.28
npm ERR! node_modules/@mendable/firecrawl-js
npm ERR!   packages/components
npm ERR!     flowise-components@2.1.3
npm ERR!     node_modules/flowise-components
npm ERR!       workspace packages/components from the root project
npm ERR!   peerOptional @mendable/firecrawl-js@"*" from langchain@0.2.20
npm ERR!     langchain@"^0.2.11" from flowise-components@2.1.3
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

已尝试的排障步骤 #

• 本地使用pnpm可正常安装所有依赖
• 尝试在部署命令中使用npm install --legacy-peer-deps、npm install --force，错误仍存在
• 验证本地与部署环境的Node.js、npm版本兼容性，确认SAP BTP Cloud Foundry NodejsBuildpack的兼容版本

解决方案思路 #

1. 强制使用pnpm的依赖解析逻辑：部署环境可能默认用npm处理依赖，需确保构建全程用pnpm。修改mta.yaml的构建命令，添加pnpm的兼容参数绕过peer依赖冲突：

   build-parameters:
     builder: custom
     commands:
       - "npm install -g pnpm@latest"
       - "pnpm install --strict-peer-deps=false"
       - "pnpm run build"
   

2. 锁定依赖版本：本地生成pnpm-lock.yaml后，将其加入部署包，确保部署环境使用与本地完全一致的依赖版本。
3. 指定Node.js版本：在mta.yaml中明确配置Node.js版本，与本地兼容版本保持一致，避免环境差异导致的依赖解析问题：

   parameters:
     buildpack: nodejs_buildpack
     node-version: 20.16.0
   

4. 添加npm配置文件：在项目根目录创建.npmrc文件，配置legacy-peer-deps=true，让npm兼容旧的peer依赖逻辑，该文件会被部署环境读取：

   legacy-peer-deps=true
   

5. 调整模块类型：当前mta.yaml中模块类型为html5，但Flowise AI是Node.js后端应用，尝试将模块类型改为nodejs，确保Buildpack正确识别应用类型：

   modules:
     - name: flowise
       type: nodejs
       # 其余参数保持不变
   

内容的提问来源于stack exchange，提问作者user3719017