通过CodeDeploy将Next.js应用部署至AWS EC2遇故障求助

一、appspec.yml 正确配置 #

Next.js应用必须先完成构建，再将构建产物部署到EC2，而非直接上传源码。appspec.yml的source要指向构建后的输出目录，而非源码根目录，这是你之前配置错误的核心原因。

不同Next.js版本的构建产物路径： #

• Pages Router（Next.js 12及更早）：构建后产物在.next目录
• App Router（Next.js 13+）：构建后产物在.next目录（SSR/SSG模式）或out目录（静态导出模式）

标准appspec.yml示例（以Pages Router为例）： #

version: 0.0
os: linux
files:
  - source: .next/
    destination: /var/www/your-next-app/.next/
  - source: public/
    destination: /var/www/your-next-app/public/
  - source: package.json
    destination: /var/www/your-next-app/
hooks:
  BeforeInstall:
    - location: scripts/install_dependencies.sh
      timeout: 300
      runas: root
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 300
      runas: ec2-user

配套脚本说明： #

• install_dependencies.sh（在EC2上安装依赖）：

  #!/bin/bash
  curl -sL https://rpm.nodesource.com/setup_18.x | bash -
  yum install -y nodejs
  cd /var/www/your-next-app
  npm install --production
  

• start_server.sh（用pm2后台启动服务，避免进程退出）：

  #!/bin/bash
  cd /var/www/your-next-app
  npm install -g pm2
  pm2 start npm --name "next-app" -- start
  pm2 save
  pm2 startup
  

你之前设置的/、pages/_app.js等source路径都不正确——CodeDeploy会上传未编译的源码，但EC2没有构建环境时，直接启动源码会导致服务无法正常响应，进而返回403。

二、Target Group 健康检查配置 #

403错误大多是健康检查路径无法正常响应或端口/权限问题，按以下配置调整：

• 健康检查路径：不要用默认的/（SSR服务可能因未完全启动或路由权限问题返回403），建议自定义健康检查接口：
  在pages/api/health.js中编写：

  export default function handler(req, res) {
    res.status(200).json({ status: 'ok' });
  }
  

  然后将Target Group的健康检查路径设为/api/health，匹配返回码200。
• 端口与协议：确保Target Group的端口和Next.js服务监听的端口一致（默认3000），协议选择HTTP（未配置HTTPS时）。
• 安全组：EC2实例的安全组要允许ALB的安全组访问3000端口；ALB的安全组需允许自身向EC2发起健康检查请求。

三、是否需要Docker/Kubernetes？ #

不需要。纯EC2 + CodeDeploy + CodePipeline完全能满足基础Next.js应用的部署需求。只有当你需要环境隔离、自动化扩缩容或复杂微服务架构时，才需要考虑Docker容器化或Kubernetes编排，你的场景用现有方案即可解决问题。

四、额外排查点 #

• 环境变量：在EC2实例中设置NODE_ENV=production，避免Next.js处于开发模式的权限限制。
• CodeDeploy权限：确保CodeDeploy服务角色拥有访问EC2实例的足够权限（如AmazonEC2FullAccess、AWSCodeDeployRole相关权限）。
• 服务运行状态：登录EC2实例，用pm2 list或ps aux | grep node检查Next.js服务是否正常运行，通过pm2 logs next-app查看启动日志排查错误。
• 文件权限：确保EC2实例的ec2-user对部署目录/var/www/your-next-app有读写权限，避免构建或启动时因权限不足失败。

内容的提问来源于stack exchange，提问作者hafiz.bhuyan