Docker镜像中使用Yarn Workspaces安装时私有工作区包找不到的解决方法

这个问题我帮很多开发者解决过——本质上就是Docker构建环境没识别到你的本地工作区包，Yarn只能傻呵呵去远程仓库找，自然找不到。下面是几个亲测有效的解决方案，按推荐度排序：

1. 确保构建时包含完整的工作区结构 #

Yarn Workspaces依赖根目录和各个子包的package.json来识别本地依赖关系，所以构建镜像时不能只复制单个子包的文件，必须把整个monorepo的核心结构带进去。

基础Dockerfile示例（适合简单场景） #

# 选择基础镜像
FROM node:18-alpine
WORKDIR /app

# 先复制根目录的依赖配置，利用Docker缓存层优化
COPY package.json yarn.lock ./
# 复制所有工作区子包的package.json（假设子包都在packages目录下）
COPY packages/*/package.json ./packages/

# 安装所有依赖（--frozen-lockfile确保依赖版本和本地一致）
RUN yarn install --frozen-lockfile

# 复制所有源代码（包括本地工作区包的代码）
COPY . .

# 编译代码（如果是TypeScript/React等需要编译的项目）
RUN yarn build

# 启动应用
CMD ["node", "./packages/your-app/dist/index.js"]

关键注意事项 #

• 不要在.dockerignore里排除packages目录，否则Yarn找不到本地工作区的包定义
• 优先复制package.json和yarn.lock再安装依赖，这样只有当依赖变更时才会重新执行yarn install，提升构建速度

2. 使用多阶段构建减小镜像体积 #

上面的方法会把开发依赖也打包进镜像，体积偏大。用多阶段构建可以分离开发构建和生产运行环境，只保留必要的生产文件。

多阶段Dockerfile示例 #

# -------------------------- 构建阶段（包含开发依赖） --------------------------
FROM node:18-alpine AS builder
WORKDIR /app

# 复制依赖配置
COPY package.json yarn.lock ./
COPY packages/*/package.json ./packages/

# 安装所有依赖（包括开发依赖，用于编译）
RUN yarn install --frozen-lockfile

# 复制所有源代码
COPY . .

# 编译项目（比如TypeScript编译、React打包等）
RUN yarn build

# -------------------------- 生产阶段（仅保留生产依赖和产物） --------------------------
FROM node:18-alpine AS production
WORKDIR /app

# 复制依赖配置
COPY package.json yarn.lock ./
COPY packages/your-app/package.json ./packages/your-app/

# 使用Yarn Workspaces Focus只安装目标包的生产依赖
RUN yarn workspaces focus --production your-app

# 从构建阶段复制编译好的产物
COPY --from=builder /app/packages/your-app/dist ./dist

# 启动应用
CMD ["node", "./dist/index.js"]

为什么这么做？ #

• yarn workspaces focus --production your-app会自动解析目标包的所有依赖，包括本地工作区的包，并且只安装生产环境需要的部分，大大减少镜像体积
• 多阶段构建把开发环境的工具和依赖完全隔离在builder阶段，生产镜像只保留运行必需的文件

3. 针对单个工作区包的优化（快速构建） #

如果只需要部署monorepo中的某一个包，可以进一步优化：在构建阶段先安装所有依赖，然后直接提取目标包的相关文件，避免复制整个monorepo的冗余代码。

优化点补充 #

在builder阶段编译完成后，可以单独把目标包的产物和依赖整理出来：

# 在builder阶段末尾添加
RUN mkdir -p /temp-app \
    && cp -r packages/your-app/dist /temp-app/dist \
    && cp packages/your-app/package.json /temp-app/

然后在production阶段直接复制这个整理好的/temp-app目录即可。

常见坑点规避 #

• 确保工作区包的依赖引用正确：在主应用的package.json中，本地工作区包的版本应该写"workspace:*"或者和子包一致的版本号，比如"@cutting/util": "1.0.0"，而不是随便写一个远程不存在的版本
• 不要手动修改yarn.lock文件，每次变更依赖后执行yarn install更新lock文件，确保Docker构建时依赖解析一致
• 如果使用私有npm仓库，记得在Dockerfile中添加仓库配置（比如RUN yarn config set registry https://your-registry.com）

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