Elastic Beanstalk部署NestJS API启动失败排查求助

1. 获取完整错误日志 #

• 登录AWS控制台，进入目标Elastic Beanstalk环境
• 左侧导航选择日志，点击请求日志→完整日志
• 下载日志包后，重点查看web.stdout.log和web.stderr.log，定位npm报错的具体原因（比如文件缺失、依赖失败、权限问题等）

2. 检查package.json关键配置 #

找到项目根目录的package.json，核对以下内容：

• scripts字段：
  • 确认build命令存在（比如"build": "nest build"），这是生成dist目录的关键
  • 检查start命令的路径：node dist/main中的dist/main.js是否为实际编译输出文件（NestJS默认编译路径是dist/main.js，若团队修改过tsconfig.json的outDir，需同步调整路径）
  • 示例正确配置：

    "scripts": {
      "build": "nest build",
      "start": "NO_COLOR=true NODE_ENV=prod node dist/main"
    }
    

• engines字段：明确Node.js和npm版本（比如"engines": {"node": ">=18.x", "npm": ">=9.x"}），需与Elastic Beanstalk环境的Node版本匹配

3. 本地验证项目可用性 #

• 本地克隆项目，执行npm install安装依赖
• 运行npm run build，确认根目录生成dist文件夹且包含main.js
• 执行npm start，验证API能在本地正常启动

4. 检查Elastic Beanstalk软件配置 #

• 进入EB环境的配置→软件
• 确认Node command为空（为空时EB默认执行npm start，若此处有自定义命令会覆盖package.json配置）
• 查看环境属性，避免NODE_ENV等变量与start命令中的设置冲突
• 核对平台版本（如Node.js 18.x）与package.json的engines要求一致

5. 配置EB自动执行构建 #

若EB部署时未自动执行build命令，需添加配置文件：

• 在项目根目录创建.ebextensions文件夹
• 新建01_build.config文件，内容如下：

  container_commands:
    01_npm_build:
      command: "npm run build"
      leader_only: true
  

• 若构建需要依赖devDependencies（如typescript、nest-cli），需在package.json添加"preinstall": "npm install --include=dev"，或在配置文件中修改命令为npm install --include=dev && npm run build

6. 排查文件权限问题 #

若日志提示权限不足（如无法读取dist/main.js），添加权限配置：

• 在.ebextensions新建02_permissions.config：

  container_commands:
    01_set_permissions:
      command: "chmod +x dist/main.js"
  

7. 重新部署测试 #

• 确保修改后的package.json和.ebextensions文件夹包含在部署包中
• 上传包到Elastic Beanstalk，查看部署日志确认构建、启动步骤无报错

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