用途:为依赖 Vercel 关联资源(数据库、认证、托管集成)的仓库执行项目引导编排,按严格顺序完成链接、资源开通与环境校验。
主要能力与规则:在 Vercel 链接完成且环境变量校验通过前,不运行 db:push、db:migrate、db:seed 或 dev;共享资源优先使用 Vercel 托管开通(vercel integration ...),仅在不可用时回退到提供商 CLI;禁止在终端输出、日志或摘要中回显密钥值。
使用方式:先做预检,确认 Vercel CLI 已安装并认证(vercel --version、vercel whoami),检查 .vercel/project.json 确认仓库链接,未链接时先查看团队与项目再链接(vercel teams ls、vercel projects ls --scope <team>、vercel link --yes --scope <team> --project <project>)。按 .env.example、.env.sample、.env.template 优先级查找模板,缺失时 cp .env.example .env.local。Postgres 首选 Vercel 托管 Neon(vercel integration guide neon、vercel integration add neon --scope <team>),再 vercel env ls 与 vercel env pull .env.local --yes;回退路径为 Vercel 仪表盘或 Neon CLI。生成 AUTH_SECRET 时不打印值,写入 Vercel 后 unset 并重新拉取。用模板键名与 .env.local 键名做差集校验,缺失列表为空才继续。之后按仓库包管理器运行 db:push、db:seed、dev,且只运行 package.json 中存在的脚本。Next.js + shadcn 项目在链接与校验后建立 UI 基线(npx shadcn@latest add ...、Geist 字体修复、bg-background text-foreground、默认深色模式)。
验证与限制:逐项确认 whoami、project.json、Postgres 路径、env pull、键差集为空、数据库命令状态、dev 启动无配置/认证/环境错误;失败即停止并报告具体步骤与补救。next-forge 项目环境文件按应用分离,运行 pnpm migrate 而非 db:push,最少需 DATABASE_URL、CLERK_SECRET_KEY、NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY、NEXT_PUBLIC_APP_URL、NEXT_PUBLIC_WEB_URL、NEXT_PUBLIC_API_URL,可选服务可先跳过但需移除对应 @repo/* 导入,并以 apps/app、apps/api、apps/web 三个根目录分别部署。