Flask+Node.js应用部署Azure App Service时npm安装失败排查

一、项目结构验证 #

你的项目结构符合Azure App Service多项目部署的常规规范，是合理的：

• 根目录：.deployment、startup.sh
• backend/：Flask后端核心文件（app.py、requirements.txt）
• frontend/：Node.js前端源码（src/、public/、package.json等）

本地能正常运行说明业务逻辑本身无问题，故障出在Azure部署阶段的脚本执行环节。

二、startup.sh执行失败核心排查点 #

1. 脚本权限与路径容错 #

Azure部署时默认以项目根目录为工作目录，但需确保脚本可执行且路径切换有容错机制：

• 脚本开头必须添加shebang声明执行环境：#!/bin/bash，否则Azure无法识别脚本类型
• 所有目录切换命令需添加错误判断，避免脚本因路径不存在直接终止，示例修正后的脚本：

  #!/bin/bash
  
  # 进入frontend目录，失败则终止脚本
  cd frontend || { echo "ERROR: Failed to access frontend directory"; exit 1; }
  echo "[BUILD] Running npm install in frontend..."
  npm install
  if [ $? -ne 0 ]; then
      echo "ERROR: npm install failed"
      exit 1
  fi
  
  echo "[BUILD] Running npm run build..."
  npm run build
  if [ $? -ne 0 ]; then
      echo "ERROR: npm run build failed"
      exit 1
  fi
  
  # 切换到backend目录
  cd ../backend || { echo "ERROR: Failed to access backend directory"; exit 1; }
  echo "[BUILD] Installing Python dependencies..."
  pip install -r requirements.txt --user
  echo "[STARTUP] Launching gunicorn..."
  gunicorn --bind=0.0.0.0 --timeout 600 app:app
  

• 本地执行chmod +x startup.sh赋予脚本可执行权限后，再提交代码到仓库

2. Node.js版本兼容性 #

Azure默认Node版本可能与本地环境不匹配，导致npm install静默失败：

• 在frontend/package.json中添加engines字段指定兼容版本：

  {
    "engines": {
      "node": "18.x",
      "npm": "9.x"
    }
  }
  

• 或通过App Service应用设置强制指定Node版本：在Azure Portal的App Service -> 配置 -> 应用程序设置中添加WEBSITE_NODE_DEFAULT_VERSION=18.x

3. 构建日志完整性 #

你提到的日志截断问题，需查看完整的SCM构建日志：

• 登录Azure Portal，进入目标App Service，依次点击部署中心 -> 日志，切换到构建日志标签，这里会包含脚本执行的所有输出（包括错误信息）
• 若日志显示脚本未被触发，检查.deployment配置是否正确：

  [config]
  SCM_DO_BUILD_DURING_DEPLOYMENT = true
  command = ./startup.sh
  

三、package-lock.json版本问题的合理性 #

Azure旧版Node运行环境对lockfileVersion 2+兼容性确实存在问题，降级到版本1是可行的临时方案。更优解是：

• 确保指定的Node版本（16.x及以上）支持lockfileVersion 2，无需降级
• 降级操作：删除现有package-lock.json，执行npm install --lockfile-version=1生成版本1的锁文件

四、替代部署方案（若脚本执行仍异常） #

如果startup.sh构建逻辑始终无法触发，可改用Azure多阶段构建：

1. 在项目根目录创建azure-pipelines.yml，分阶段完成前端构建、后端依赖安装与部署
2. 或使用App Service的Kudu部署钩子，通过自定义脚本触发构建流程

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