Docker Compose部署NextJS应用报错：npm ci需package-lock.json

问题 #

在新的AWS虚拟机上执行sudo docker compose -f compose/docker-compose.yaml up部署NextJS应用容器时，出现如下报错：

> [... builder 4/6] RUN npm ci:
1.721 npm error code EUSAGE
1.722 npm error
1.722 npm error The `npm ci` command can only install with an existing package-lock.json or
1.722 npm error npm-shrinkwrap.json with lockfileVersion >= 1. Run an install with npm@5 or
1.722 npm error later to generate a package-lock.json file, then try again.
1.722 npm error
1.722 npm error Clean install a project
1.722 npm error
1.722 npm error Usage:
1.722 npm error npm ci
1.722 npm error
1.722 npm error Options:
1.722 npm error [--install-strategy <hoisted|nested|shallow|linked>] [--legacy-bundling]
1.722 npm error [--global-style] [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
1.722 npm error [--include <prod|dev|optional|peer> [--include <prod|dev|optional|peer> ...]]
1.722 npm error [--strict-peer-deps] [--foreground-scripts] [--ignore-scripts] [--no-audit]
1.722 npm error [--no-bin-links] [--no-fund] [--dry-run]
1.722 npm error [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
1.722 npm error [-ws|--workspaces] [--include-workspace-root] [--install-links]
1.722 npm error
1.722 npm error aliases: clean-install, ic, install-clean, isntall-clean
1.722 npm error
1.722 npm error Run "npm help ci" for more info

前置说明 #

已查阅过GitHub Actions相关的类似问题，但未找到针对Docker场景的有效解决方案。

操作步骤 #

尝试将NextJS应用通过Docker容器部署到AWS虚拟机，具体步骤如下：

1. 在本地PC执行docker compose -f compose/docker-compose.yaml up，compose文件夹内文件如下：
   • .dockerignore:

     .env
     Dockerfile.prod
     .dockerignore
     .next
     .git
     .gitignore
     node_modules
     npm-debug.log
     README.md
     

   • DockerFile.prod:

     # Development Stage
     FROM node:20.18.1-alpine AS development
     WORKDIR /app
     COPY package*.json package-lock.json ./
     RUN npm ci
     COPY . .
     EXPOSE 3000
     CMD ["npm", "run", "dev"]
     
     # Builder Stage
     FROM node:20.18.1-alpine AS builder
     WORKDIR /app
     COPY package*.json package-lock.json ./
     RUN npm ci
     COPY . .
     RUN npm run build
     
     # Production Stage 
     FROM node:20.18.1-alpine AS production
     WORKDIR /app
     # Copy the built artifacts from the builder stage
     COPY --from=builder /app/.next/standalone ./
     COPY --from=builder /app/.next/static ./.next/static
     # Set the environment variables (if needed)
     ENV NODE_ENV=production
     EXPOSE 3000
     CMD ["node", "server.js"]
     

   • docker-compose.yaml:

     services:
       web-app:
         build:
           context: ../
           dockerfile: compose/DockerFile.prod
           target: production
           args:
             NEXT_PUBLIC_CLIENTVAR: "clientvar"
         ports:
           - 3000:3000
         environment:
           - NODE_ENV=production
         depends_on:
           - db
         restart: unless-stopped
       db:
         image: postgres:14.15
         container_name: postgres
         ports:
           - 5433:5432
         environment:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: password
           POSTGRES_DB: postgres
         volumes:
           - postgres-data:/var/lib/postgresql/data
         restart: unless-stopped
     volumes:
       postgres-data:
     

2. 为Web应用打标签并推送到Dockerhub容器仓库；
3. 在AWS虚拟机上安装Docker并登录；
4. 从Dockerhub拉取Web应用容器；
5. 在虚拟机上创建/compose文件夹及相关Docker文件；
6. 执行sudo docker compose -f compose/docker-compose.yaml up，触发上述报错。

解决方案 #

核心原因 #

报错明确指出npm ci必须依赖已存在的package-lock.json或npm-shrinkwrap.json文件（且lockfileVersion >=1）。你的场景中，要么是本地项目未生成该文件，要么是Docker构建上下文里没有包含这个文件，导致构建阶段无法执行npm ci。

具体修复步骤 #

1. 生成本地package-lock.json
   在本地项目根目录执行：

   npm install
   

   这会自动生成或更新package-lock.json，npm@5+版本默认生成的文件都满足lockfileVersion要求。

2. 简化Dockerfile复制逻辑
   当前Dockerfile中COPY package*.json package-lock.json ./可以简化为COPY package*.json ./，因为package*.json已包含package-lock.json，避免拼写错误导致文件未复制：

   # Builder Stage 修改示例
   FROM node:20.18.1-alpine AS builder
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci
   COPY . .
   RUN npm run build
   

3. 直接运行已推送的镜像（推荐）
   你已经将本地构建好的镜像推送到Dockerhub，无需在AWS虚拟机上重复构建。修改虚拟机上的docker-compose.yaml，替换build配置为image指定镜像地址：

   services:
     web-app:
       image: 你的DockerHub用户名/你的镜像名:标签
       ports:
         - 3000:3000
       environment:
         - NODE_ENV=production
       depends_on:
         - db
       restart: unless-stopped
     # db部分保持不变
   

   这样直接运行已打包好的镜像，彻底避开构建阶段的npm ci报错。

4. 若必须在虚拟机构建
   确保虚拟机上的项目根目录包含package-lock.json，且docker-compose.yaml中context路径正确指向包含package.json和package-lock.json的目录。

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