如何使用Yarn Workspaces将Monorepo部署至Vercel

前置准备 #

• 本地已安装Yarn（1.x/2+版本均可，以下以1.x为例）和Vercel CLI
• Monorepo已通过Yarn Workspaces完成基础配置，根目录package.json已声明workspaces字段

典型项目结构示例 #

your-monorepo/
├── package.json
├── packages/
│   ├── frontend/          # 待部署的前端项目（如Next.js/React CRA）
│   │   ├── package.json
│   │   └── next.config.js
│   └── shared/            # 共享工具/组件包
│       └── package.json
└── vercel.json

具体部署步骤 #

1. 根目录package.json配置 #

确保workspaces声明正确，同时添加私有标识和构建脚本：

{
  "name": "your-monorepo",
  "private": true,
  "workspaces": ["packages/*"],
  "scripts": {
    "install": "yarn install",
    "build:shared": "yarn workspace shared build", // 若共享包需编译
    "build:frontend": "yarn build:shared && yarn workspace frontend build"
  }
}

• private: true 避免整个Monorepo被意外发布
• 拆分构建脚本，确保共享包编译完成后再构建前端项目

2. 两种部署配置方式 #

方式一：Vercel CLI部署

1. 根目录登录Vercel：vercel login
2. 初始化项目：vercel，按提示选择团队、项目名称
3. 关键交互配置：
   • 安装命令：输入yarn install
   • 构建命令：输入yarn build:frontend
   • 输出目录：输入前端项目的构建产物路径，如packages/frontend/.next（Next.js）或packages/frontend/build（React CRA）

方式二：Vercel Dashboard部署

1. 将Monorepo代码推送到GitHub/GitLab等仓库
2. 在Vercel控制台新建项目并导入该仓库
3. 进入「Build & Development Settings」配置：
   • Install Command: yarn install --frozen-lockfile（锁定依赖版本，提升构建稳定性）
   • Build Command: yarn build:frontend
   • Output Directory: packages/frontend/.next（根据项目类型调整）

3. 可选：通过vercel.json统一配置 #

在根目录创建vercel.json，固化部署规则：

{
  "installCommand": "yarn install --frozen-lockfile",
  "buildCommand": "yarn build:frontend",
  "outputDirectory": "packages/frontend/.next",
  "framework": "nextjs" // 指定框架可获得Vercel专属优化
}

4. 环境变量配置 #

• 在Vercel控制台项目的「Settings」->「Environment Variables」中添加所需变量，支持区分开发/预览/生产环境
• 也可在前端项目目录下创建.env文件（注意不要提交敏感信息到仓库）

常见问题解决 #

• 共享包找不到：确保共享包的package.json中main/module字段指向编译后的文件，前端项目依赖共享包时使用"shared": "workspace:*"格式
• 构建速度慢：启用Vercel的「Install Cache」功能，缓存node_modules以加快后续部署
• 依赖安装冲突：强制指定安装命令为yarn install，避免Vercel默认使用npm导致依赖不一致

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