将Node.js应用部署至GCP App Engine遇500错误：模块缺失且无实例

核心问题 #

部署无报错但访问触发500错误，日志显示找不到编译后的主模块文件/workspace/dist/main，同时实例未按预期启动2个。结合收到的Container Registry迁移至Artifact Registry邮件，大概率是构建环境或部署包内容异常导致。

排查与解决步骤 #

1. 确认部署包包含dist产物 #

• 本地执行nest build后，确保当前部署目录下存在完整的dist文件夹
• 检查.gitignore文件，确认未将dist列为忽略项（gcloud app deploy默认会排除.gitignore中的内容）
• 执行部署时加调试日志查看文件上传情况：

  gcloud app deploy --verbosity=debug
  

  日志中会显示上传的文件列表，确认dist/main.js在其中

2. 排查Artifact Registry迁移导致的构建环境变化 #

• 检查package.json的engines字段，确认Node版本与本地一致，例如：

  "engines": {
    "node": "18.x"
  }
  

• 若使用云端构建（Cloud Build），前往GCP控制台查看Cloud Build的详细日志，确认：
  • npm install是否成功完成
  • nest build命令是否被执行，有无编译报错
  • 构建镜像的Node版本是否符合项目要求

3. 验证app.yaml配置正确性 #

• 检查entrypoint配置是否指向正确的文件路径，示例：

  entrypoint: node dist/main.js
  

  若应用运行的工作目录不是根目录，需调整为绝对路径（如node /workspace/dist/main.js），但通常App Engine默认工作目录为应用根目录
• 确认app.yaml中未配置错误的构建规则，导致云端未生成dist文件

4. 本地模拟云端构建环境测试 #

• 拉取与Artifact Registry一致的Node镜像，本地模拟构建过程：

  docker pull node:18-alpine
  docker run -v $(pwd):/workspace -w /workspace node:18-alpine sh -c "npm install && nest build"
  

  查看容器内是否生成了dist/main.js，若失败则说明依赖或构建命令存在环境兼容问题

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