在Azure App Service中用pm2运行Express应用失败：CLI未找到

我正尝试通过GitHub Actions把基于node-express-boilerplate模板的Express API部署到关联master分支的Azure App Service。本地运行完全正常，但在Azure上执行npm run start或yarn run start时，出现pm2模块找不到的错误；在Kudu中执行npm run dev时，cross-env也报类似的模块找不到错误。

pm2启动错误日志 #

Error: Cannot find module '../lib/binaries/CLI.js'
Require stack:
- /home/site/wwwroot/node_modules/.bin/pm2
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:902:15)
    at Function.Module._load (internal/modules/cjs/loader.js:746:27)
    at Module.require (internal/modules/cjs/loader.js:974:19)
    at require (internal/modules/cjs/helpers.js:101:18)
    at Object.<anonymous> (/home/site/wwwroot/node_modules/.bin/pm2:3:1)
    at Module._compile (internal/modules/cjs/loader.js:1085:14)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
    at Module.load (internal/modules/cjs/loader.js:950:32)
    at Function.Module._load (internal/modules/cjs/loader.js:790:12)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:75:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/home/site/wwwroot/node_modules/.bin/pm2' ]
}

GitHub Actions流水线配置 #

name: Build and deploy Node.js app to Azure Web App - xxx

on:
  push:
    branches:
      - master
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Set up Node.js version
        uses: actions/setup-node@v1
        with:
          node-version: '18.x'

      - name: npm install, build, and test
        run: |
          npm install
          npm run build --if-present

      - name: Upload artifact for deployment job
        uses: actions/upload-artifact@v2
        with:
          name: node-app
          path: .

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: 'Production'
      url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}

    steps:
      - name: Download artifact from build job
        uses: actions/download-artifact@v2
        with:
          name: node-app

      - name: 'Deploy to Azure Web App'
        id: deploy-to-webapp
        uses: azure/webapps-deploy@v2
        with:
          app-name: 'xxx'
          slot-name: 'Production'
          publish-profile: ${{ secrets.xxxB }}
          package: .

项目配置文件（ecosystem.config.json） #

{
    "apps": [
        {
            "name": "app",
            "script": "src/index.js",
            "instances": 1,
            "autorestart": true,
            "watch": false,
            "time": true,
            "env": {
                "NODE_ENV": "production"
            }
        }
    ]
}

cross-env执行错误日志 #

internal/modules/cjs/loader.js:905
  throw err;
  ^

Error: Cannot find module '..'
Require stack:
- /home/site/wwwroot/node_modules/.bin/cross-env
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:902:15)
    at Function.Module._load (internal/modules/cjs/loader.js:746:27)
    at Module.require (internal/modules/cjs/loader.js:974:19)
    at require (internal/modules/cjs/helpers.js:101:18)
    at Object.<anonymous> (/home/site/wwwroot/node_modules/.bin/cross-env:3:18)
    at Module._compile (internal/modules/cjs/loader.js:1085:14)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
    at Module.load (internal/modules/cjs/loader.js:950:32)
    at Function.Module._load (internal/modules/cjs/loader.js:790:12)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:75:12) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [ '/home/site/wwwroot/node_modules/.bin/cross-env' ]
}

已尝试的解决操作 #

• 匹配本地与Azure的Node版本（均为18.16）
• 通过Kudu卸载所有依赖模块、删除package-lock.json、重装pm2、手动重装整个项目

解决思路 #

1. 避免跨环境传递node_modules #

当前流水线在Ubuntu环境安装依赖后直接上传node_modules到Azure，不同系统的二进制依赖可能不兼容，且上传过程可能丢失文件。修改流水线：

• 移除构建阶段的npm install命令，仅保留npm run build --if-present
• 调整artifact上传范围，只上传源代码、配置文件和构建产物：

  - name: Upload artifact for deployment job
    uses: actions/upload-artifact@v2
    with:
      name: node-app
      path: |
        src/
        package.json
        package-lock.json
        ecosystem.config.json
        # 若有build产物，添加对应目录如dist/
  

Azure会自动检测package.json并在部署后安装依赖，确保依赖与运行环境兼容。

2. 修正pm2的调用路径 #

.bin目录下的pm2脚本路径解析异常，可直接调用pm2的核心文件：
修改package.json的start命令：

"start": "node node_modules/pm2/bin/pm2.js start ecosystem.config.json"

或者先跳过pm2，直接用node src/index.js启动API，确认正常后再加入pm2管理。

3. 检查文件权限与完整性 #

通过Kudu控制台：

• 确认node_modules/pm2/lib/binaries/CLI.js和node_modules/cross-env/lib/index.js是否存在，若缺失说明依赖安装不完整，可手动执行npm install重新安装
• 若文件存在但权限不足，执行chmod +x node_modules/.bin/pm2和chmod +x node_modules/.bin/cross-env赋予执行权限

4. 配置Azure App Service启动命令 #

进入Azure门户的App Service配置页面，在“启动命令”中明确指定启动指令，比如：

npm run start

或临时使用node src/index.js测试基础功能是否正常。

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