use-vercel-deploy-in-monorepo

仓库原始内容

按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Monorepo 与独立仓库的 Vercel 部署

适用范围与排除范围

用于 pnpm workspace 或独立仓库的 Nuxt、Nitro、Vite、UniApp H5 等部署。一个 Git 仓库可关联多个 Vercel Project，但每个 Project 都必须单独验收。

不处理 GitHub Actions、GitHub Workflow 或其他自建 CI 部署。未经用户授权，不提交、推送、修改真实云端配置、unlink 或删除团队资源。

不可跳过纪律

正式交付链是 Vercel Git Integration。 Git push 触发的目标 Project 部署才是正式验收；本地 CLI upload、MCP 触发和 Prebuilt 仅用于构建诊断、产物核验或已明确授权的应急辅助链。
本地 link 是单槽绑定。 每次切换目标 Project，或在任意目录执行交互式本地部署前，都先运行 vercel link --project <project-name> --yes，随后在同一执行目录读取 .vercel/project.json，将 projectId 和 orgId 分别与目标 Project、目标团队的远端值精确比较。字段缺失或不一致立即停止；不能只按项目名或目录名判断。vercel link 只绑定本地 CLI Project，绝不证明 Vercel Project 已连接 Git 仓库。
先决定 Node，后设计构建。 在编写 Build Command、Turbo 依赖和远端设置前，根据 engines.node、版本文件、包管理器、依赖兼容性、远端 nodeVersion 与当前官方支持范围，在 22.x 与 24.x 中做有证据的选择；两个均可用时沿用仓库基线，证据不足不升级。
所有远端写入均需读后校验。 Settings 固定 GET → 比较 → 最小 PATCH → GET → inspect；Shared Environment Variables 固定 GET → 精确识别 → 冲突检查 → 增量 PATCH → GET。权限、字段或回读失败时停止，不猜测成功。
不得泄露或替代团队资源。 不打印 token、secret value 或私有认证文件；普通项目变量不等于 Shared Environment Variable link。默认仅补齐明确声明的缺失链接，unlink 需明确授权，删除默认禁止。

P0 阶段门禁

侦察目标仓库、生产分支、目标团队/Project、Root Directory、Git 连接和当前部署来源。
明确 Git Integration 为正式主链；确认本地 Prebuilt 只作辅助。
为每个目标 Project 分别建立或核实 Git repository connection 与 Production Branch。新 Project 从 Dashboard 导入 Git 仓库；既有 Project 在 Settings 中连接/更换仓库并设置 Production Branch。公共文档没有稳定写 API 时必须停在 Dashboard 人工 gate，完成回读前标记阻塞；完整路径与证据见Git 部署与诊断。
决定 Node 22.x 或 24.x，并写下依据与远端当前值。
如需本地人工操作，完成 CLI 单槽 link 与 projectId/orgId 双 ID gate（见CLI 与远端读取）。
读取、比较并最小化更新 Project Settings（见Settings 写回）。Root Directory 不在默认 PATCH allowlist；修改它需要用户单独授权并重新评估命令和产物。
分别审计 Production、Preview、Development 的项目变量与 Shared Environment Variables；仅按共享变量完成真实的团队变量链接。
在本地运行构建并检查 .vercel/output，但不将其等同于 Git 主链成功。
获得推送授权后，以可识别 commit SHA 触发 Git 部署，并完成Git E2E。
更新目标项目 README 与已存在的 AI 记忆（见项目部署文档）。

P1 交付质量门禁

审查 .vercelignore，避免忽略 workspace、构建输入、运行时文件或错误排除 .vercel/output。
按上传、安装、构建、产物、运行时、域名六层分诊日志；先确认部署来源是 Git clone、CLI upload 还是 Prebuilt。
对 Nitro，核验 serverDir 与真实目录、functions 产物和 API 冒烟；对 Turbo，使用 dependsOn 和 outputs 表达跨包依赖，禁止用多步骤 shell 串接替代任务图。
分别验证 Production、Preview、Development 作用域；保留首次 E2E 的逐项证据而非只勾选。

Git 主链与本地辅助链

Git 主链的证据顺序为：推送 commit → Vercel 克隆/checkout 仓库 → Install → Build → Output → READY → 目标 URL 冒烟。日志中的 Cloning 或等价 Git checkout，加上匹配的 commit SHA，才可证明 Git 主链；Downloading deployment files 只可证明文件上传或 Prebuilt 路径。

本地 Prebuilt 只可验证本地 build 与 .vercel/output，或帮助区分本地代码问题与云端 Git 环境问题。本地 READY 不能关闭任何 Git E2E 项。完整分诊和 E2E 见Git 部署与诊断。

写入与能力路由

优先级固定为：CLI 专用命令 → vercel api → 直接 REST API → MCP → Dashboard。

CLI 用于 link、project inspect、部署和日志；先探测 vercel api --help，再决定是否可调用 API。
vercel api 或直接 REST API 用于 Settings、Shared Variable 等没有 CLI 专用写命令的场景；REST token 只读 VERCEL_TOKEN 环境变量。
MCP 仅辅助项目、部署和日志读取；它不是 Settings 或 Shared Variable 写入的替代，尤其不得声称 MCP 能 Link Shared Variable。能力边界见MCP 操作。
上述自动写入路径均不可用时，给出 Dashboard 操作位置并标记为阻塞，不能虚构配置已写入。

构建、产物与框架路由

按monorepo 部署模式先选择模式 A（根 .vercel/output）或模式 B（子包直接产物），并保持 Root Directory、Build Command、Install Command 与 Output Directory 同一口径。

按实际框架使用可复制模板，并同时选择对应 Turbo 任务模板：

Nitro 的服务端源码不在默认位置时，先读取 nitro.config.*，核对 serverDir 与目录存在性；构建后检查 functions 产物，首次 Git E2E 覆盖该目录提供的 API。不要用 build 成功代替运行时验证。

符号链接产物搬运（仅模式 A）

move-vercel-output-to-root 负责把子包的 .vercel/output 搬到 Vercel 在仓库根读取的 .vercel/output。它的 --dereference 是复制策略开关，不是 Nitro、pnpm/Corepack 或运行时配置开关，默认必须保持关闭。

参数	默认值	语义与边界
`--root-dir <path>`	自动发现 workspace 根	仅在自动发现不适用时显式指定 monorepo 根
`--source-dir <path>`	子包 `.vercel/output`	必须是本次构建真实写入的源目录
`--target-dir <path>`	根 `.vercel/output`	必须与 Project 的 Output Directory 口径一致
`--skip-clean`	`false`	仅在已验证需要合并多个独立产物时使用；不能用来规避陈旧函数
`--dry-run`	`false`	只显示解析路径和策略，不复制或清理；不能替代真实产物检查
`--dereference`	`false`	将符号链接指向的实体文件/目录复制到目标；只对受信任产物按证据启用

编程式 API 使用 dereference?: boolean；解析结果和构建日志必须记录最终布尔值。

启用前按顺序确认：

Vercel 使用模式 A，且根 .vercel/output 是最终读取目录；模式 B 或独立仓库不应增加根搬运。
运行真实 build:vercel，分别检查子包和根目录 .vercel/output/functions。
用 lstat 或等价检查确认待搬运的 .func 项确实是符号链接，并保留未解引用时的可复现函数拓扑、路由或消费失败证据。
确认链接及其目标都来自本次受信任构建产物；不得把受控目录外的内容带入部署。
启用后确认根输出中的目标 .func 已实体化，并从 Vercel Git 构建日志读取解析结果，再完成目标 API 冒烟。

只有以上条件同时成立时，才在原子搬运任务中加入 --dereference。普通文件复制行为应保持不变；--dry-run 必须显示 dereference，且不得复制或清理。不要因为 ERR_PNPM_META_FETCH_FAIL、Corepack/Node 漂移、Nitro compatibilityDate 未确认或 API 运行时 5xx 而启用它：这些分别属于安装、Nitro 配置或运行时层，应按对应层排查。

README 与 AI 记忆收口

部署事实必须写回目标项目 README，并等价更新已存在的 AGENTS.md、CLAUDE.md、GEMINI.md。三份 AI 记忆均缺失时转交 init-ai-md，不创建项目专属部署 skill。字段和安全边界见项目部署文档。

首次 Git E2E checklist

[ ] Git 仓库、生产分支、目标团队/Project 和 Root Directory 已核实。
[ ] 每个 Project 已独立完成 Git repository connection 与 Production Branch 设置；Project GET 的 link 实际字段及 Dashboard Branch Tracking 证据已回读，缺失项标为阻塞。
[ ] Node 22.x/24.x 选择与理由已记录，远端 nodeVersion 已比较。
[ ] 若执行本地操作，vercel link --project 后 .vercel/project.json 的 projectId、orgId 已与远端目标精确一致。
[ ] Settings 已完成最小 PATCH、GET 回读与 vercel project inspect 交叉验证，或明确记录无需变更。
[ ] 项目变量与 Shared Environment Variables 均已覆盖三环境；Shared link 无同名项目变量遮蔽并已回读。
[ ] .vercelignore、Turbo DAG、Nitro serverDir 和 .vercel/output 已检查。
[ ] 已确认 Root Directory、Output Directory 与模式 A 的根 .vercel/output 口径一致；子包和根输出的 .func 链接状态已记录，并说明 dereference 为 true 或 false 的依据。
[ ] 若启用 --dereference，已确认源产物受信任、根输出已实体化且没有越出受控目录；Git 构建日志中的解析值与预期一致。
[ ] 在获得授权后，已推送可识别 commit，并以 SHA、Git checkout 日志、READY 与 URL 冒烟完成正式 Git E2E。
[ ] README 与已有 AI 记忆已收口；未记录 token、secret 或本机私有路径。