AWS Fargate无法运行指定环境构建的Next.js应用问题

将Next.js应用容器化后部署至AWS Fargate，使用含ENV构建参数的Dockerfile，通过Jenkins传递ENV参数构建镜像，同时在ECS任务定义中配置环境变量ENV为qa。运行任务时出现npm未知命令“start-qa”的错误，该问题在AWS App Runner中也出现过。

相关配置信息 #

Dockerfile #

#Base Image
FROM node:18-alpine
ARG ENV=$ENV
RUN mkdir -p /usr/app/
WORKDIR /usr/app/
COPY . .
RUN ls -l
RUN npm install
RUN npm run build-qa
EXPOSE 3000
CMD ["npm", "start-qa"]

ECS任务定义 #

{"taskDefinitionArn": "arn:aws:ecs:region:**********:task-definition/NextJs-task:6", "containerDefinitions": [{"name": "NextJs-container", "image": "**********.dkr.ecr.region.amazonaws.com/next-js-app:latest", "cpu": 1024, "portMappings": [{"containerPort": 3000, "hostPort": 3000, "protocol": "tcp"}], "essential": true, "environment": [{"name": "ENV", "value": "qa"}], "mountPoints": [], "volumesFrom": [], "logConfiguration": {"logDriver": "awslogs", "options": {"awslogs-create-group": "true", "awslogs-group": "/ecs/NextJs", "awslogs-region": "region", "awslogs-stream-prefix": "ecs"}}}, "family": "NextJs-task", "taskRoleArn": "arn:aws:iam::**********:role/ecsTaskExecutionRole", "executionRoleArn": "arn:aws:iam::**********:role/ecsTaskExecutionRole", "networkMode": "awsvpc", "revision": 6, "volumes": [], "status": "ACTIVE", "requiresAttributes": [{"name": "com.amazonaws.ecs.capability.logging-driver.awslogs"}, {"name": "ecs.capability.execution-role-awslogs"}, {"name": "com.amazonaws.ecs.capability.ecr-auth"}, {"name": "com.amazonaws.ecs.capability.docker-remote-api.1.19"}, {"name": "com.amazonaws.ecs.capability.task-iam-role"}, {"name": "ecs.capability.execution-role-ecr-pull"}, {"name": "com.amazonaws.ecs.capability.docker-remote-api.1.18"}, {"name": "ecs.capability.task-eni"}, {"name": "com.amazonaws.ecs.capability.docker-remote-api.1.29"}], "placementConstraints": [], "compatibilities": ["EC2", "FARGATE"], "requiresCompatibilities": ["FARGATE"], "cpu": "2048", "memory": "4096", "registeredAt": "**************", "registeredBy": "arn:aws:sts::**********:assumed-role/aws-sre/-------------"}

错误信息 #

To see a list of supported npm commands, run:
npm help
Unknown command: "start-qa"
Did you mean one of these?
npm start # Start a package
npm run start-qa # run the "start-qa" package script
npm run start-uat # run the "start-uat" package script

构建命令 #

docker build --build-arg ENV=$ENV -t next-js-app .

问题原因与解决方法 #

问题原因 #

start-qa是package.json中定义的自定义脚本，并非npm内置命令。npm执行自定义脚本必须使用npm run前缀，直接用npm start-qa会被识别为未知命令。

解决方法 #

1. 修改Dockerfile的CMD命令
   将Dockerfile中的启动命令改为：

   CMD ["npm", "run", "start-qa"]
   

2. 优化Dockerfile实现动态脚本执行（可选）
   当前Dockerfile中ARG参数未被实际使用，构建和启动脚本均为硬编码的build-qa和start-qa。若需根据构建参数ENV动态切换环境脚本，可修改Dockerfile如下：

   #Base Image
   FROM node:18-alpine
   ARG ENV=qa  # 设置默认环境为qa
   RUN mkdir -p /usr/app/
   WORKDIR /usr/app/
   COPY . .
   RUN ls -l
   RUN npm install
   RUN npm run build-${ENV}
   EXPOSE 3000
   CMD ["sh", "-c", "npm run start-${ENV}"]
   

   构建时传递不同ENV参数即可自动执行对应环境脚本，例如执行docker build --build-arg ENV=uat -t next-js-app .时，会自动运行build-uat和start-uat脚本。

注意：ECS任务定义中配置的ENV环境变量是运行时变量，与Dockerfile中的ARG构建参数作用阶段不同，本次报错与ECS环境变量配置无关。

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