单体仓库（Monorepo）结构下Docker Compose配置故障排查

问题根源分析 #

1. 卷挂载覆盖容器内依赖：compose.yaml中- ./api:/api会将本地/api目录完全覆盖容器内的/api目录，本地开发时node_modules通常不会提交到仓库，导致容器内通过RUN yarn install安装的依赖被覆盖为空，引发模块找不到的错误。
2. Dockerfile 依赖安装路径不匹配：Monorepo根目录存在package.json和yarn.lock，但原Dockerfile将依赖文件复制到/api目录并在该目录执行安装，若采用Yarn工作区模式，会导致依赖安装位置错误，Node.js无法正确识别模块路径。

一、修复 Dockerfile 配置 #

适配Monorepo工作区逻辑，优化依赖安装路径与代码复制顺序：

FROM node:16

# 容器内根目录作为工作区根目录
WORKDIR /app

# 先复制Monorepo根目录的依赖文件，利用Docker缓存
COPY package.json yarn.lock ./

# 启用Yarn工作区模式，安装所有项目依赖
RUN yarn install --frozen-lockfile

# 复制API目录代码到容器工作区
COPY ./api ./api

# 切换到API目录执行启动命令
WORKDIR /app/api

EXPOSE 4000

CMD ["node", "src/index.js"]

二、调整 Docker Compose 配置 #

修改卷挂载规则，避免覆盖容器内node_modules，同时优化构建逻辑：

version: '3.8'

services:
  db:
    image: postgres:15
    restart: always
    env_file:
      - ./api/.env
    ports:
      - 5433:5432
    volumes:
      - ./docker/postgres:/var/lib/postgresql/data

  api:
    build:
      context: ./
      dockerfile: ./api/Dockerfile
    ports:
      - "4000:4000"
    depends_on:
      - db
    env_file:
      - ./api/.env
    # 仅挂载API源码目录，保留容器内的node_modules不被覆盖
    volumes:
      - ./api/src:/app/api/src
      # 若需热更新package.json，可单独挂载，但修改后需重新构建镜像安装依赖
      # - ./api/package.json:/app/api/package.json

三、额外优化建议 #

• 确认Monorepo工作区配置：根目录package.json需正确声明工作区：

  {
    "private": true,
    "workspaces": [
      "api",
      "apps/*"
    ]
  }
  

• 构建缓存利用：Dockerfile中先复制依赖文件再执行安装，仅当依赖文件变化时才会重新安装依赖，提升构建速度。
• 依赖验证：构建完成后可进入容器执行yarn list，确认依赖是否正确安装在工作区对应路径。

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