Docker Compose跨环境异常：NestJS项目Ubuntu部署启动失败

1. 核对Docker与Docker Compose版本差异 #

• 分别在本地Mac和远程Ubuntu执行以下命令，确认版本是否一致：

  docker --version
  docker compose version
  

  注意Docker Compose v1（docker-compose命令）和v2（docker compose命令）的行为差异，确保远程使用的命令与本地一致。

2. 验证镜像内的dist目录完整性 #

• 远程环境下，直接运行镜像并检查dist目录是否存在且包含main文件：

  docker run --rm <你的镜像名称> ls -la /usr/src/app/dist
  

  如果没有dist目录或main文件，说明镜像构建过程有问题：
  • 检查远程构建时的日志，确认npm run build是否执行成功，有没有报错
  • 核对Dockerfile的构建步骤：如果是多阶段构建，确保COPY --from=builder命令正确将build阶段的dist目录复制到运行时镜像中
  • 确认远程构建环境的Node版本与本地一致（Dockerfile中指定的Node镜像标签要固定，比如node:18-alpine而非node:latest）

3. 检查Docker Compose的Volume挂载配置 #

• 查看docker-compose.yml中的volumes字段，是否存在将本地目录挂载到容器/usr/src/app/dist的配置（比如./dist:/usr/src/app/dist）
  • 如果有这种挂载，远程实例当前工作目录下如果没有生成dist目录，会覆盖容器内的dist目录，导致文件丢失
  • 若不需要本地目录挂载，直接删除该volume配置；若需要，确保远程实例的当前目录下已执行npm run build生成dist文件

4. 校验环境变量配置 #

• 确认远程的.env.docker文件与本地内容一致，重点检查是否有影响构建或启动路径的变量：
  • 比如是否设置了OUTPUT_DIR等自定义构建输出目录变量，导致构建产物不在默认的dist目录中
  • 可以进入容器打印环境变量验证：

    docker run --rm --env-file .env.docker <你的镜像名称> env | grep -E "(OUTPUT_DIR|NODE_ENV)"
    

5. 排查文件权限问题 #

• Ubuntu的文件权限机制与Mac不同，可能导致容器内无法读取dist目录：
  • 进入运行失败的容器（如果容器能启动但报错，用docker exec -it <容器ID> /bin/sh），查看dist目录的权限：

    ls -la /usr/src/app
    

  • 如果权限异常，可在Dockerfile中添加设置权限的命令，比如：

    RUN chown -R node:node /usr/src/app/dist
    

  • 同时确保容器启动用户（比如node用户）有读取dist目录的权限

6. 彻底清理远程环境的缓存 #

• 执行以下命令完全清理旧容器、镜像、卷和缓存：

  docker compose down -v --rmi all --remove-orphans
  docker system prune -af
  

  之后重新构建或拉取镜像，再执行docker compose --env-file .env.docker up

7. 检查远程实例磁盘空间 #

• 用以下命令检查远程Ubuntu的磁盘使用情况，确保有足够空间生成构建产物：

  df -h
  

  如果磁盘已满，清理冗余文件后再重新构建部署

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