Skip to content

文档部署 ​

文档站通过 Vercel 的 GitHub 集成自动部署。仓库根目录的 vercel.json 固定了安装、构建和产物目录,避免 Vercel 在 monorepo 中误构建后台模板。

首次连接 Vercel ​

  1. 在 Vercel 中导入本 GitHub 仓库;
  2. 将 Root Directory 保持为仓库根目录,不要选择 apps/docs;
  3. 将生产分支设置为 main;
  4. 完成首次部署,并确认 Vercel 读取了根目录的 vercel.json,构建日志执行了 pnpm docs:build。

仓库配置如下:

配置值
Install Commandpnpm install --frozen-lockfile
Build Commandpnpm docs:build
Output Directoryapps/docs/.vitepress/dist
Clean URLstrue,与 VitePress 的无扩展名链接保持一致

Push 后的行为 ​

  • push 到非生产分支:Vercel 创建 Preview Deployment;
  • push 或合并到 main:Vercel 创建 Production Deployment;
  • 同一分支连续 push:Vercel 最终部署该分支的最新提交。

Vercel 的 Git 集成负责监听 GitHub push,不需要额外维护一套包含 Vercel Token 的 GitHub Actions 部署任务。现有 GitHub Actions 继续负责全仓质量检查,Vercel 负责文档构建与发布。

模板演示站 ​

模板演示使用独立 Vercel 项目 kevairy-template,与文档站连接同一个 GitHub 仓库及 main 生产分支。

配置值
Root Directoryapps/template
Framework PresetVite
Install Commandpnpm install --frozen-lockfile
Build Commandpnpm build
Output Directorydist
Include source files outside Root Directory开启,供 workspace 组件包构建使用

模板项目使用 apps/template/vercel.json 显式指定构建命令与产物目录,避免继承仓库根目录面向文档站的配置。该文件也随脚手架模板发布。演示站使用模板自带的 Mock 登录和示例数据;CRUD 工作台操作列的“查看”用于体验 KvDrawer。

组件 npm 包与模板 npm 包独立发布,发布顺序为先组件、后引用该版本组件的模板。在线演示站从 workspace 源码构建,不以 npm 发布完成作为自动部署触发条件。

本地验证 ​

提交部署配置或文档变更前运行:

bash
pnpm docs:build
pnpm docs:preview

本地产物位于 apps/docs/.vitepress/dist,该目录由构建生成,不提交到 Git。

排查部署没有触发 ​

依次检查:

  1. Vercel 项目是否仍连接到正确的 GitHub 仓库;
  2. Vercel 项目的 Git 设置是否启用了目标分支部署;
  3. Production Branch 是否为 main;
  4. Root Directory 是否为仓库根目录;
  5. 当前部署是否读取了仓库根目录的 vercel.json;
  6. GitHub commit checks 与 Vercel 构建日志中的具体错误。

若部署状态为 BLOCKED 且提示无法识别提交作者,检查提交邮箱是否与自己的 GitHub 账号关联,并确认 Vercel 登录连接匹配该账号。为后续提交使用该账号已验证的邮箱或 GitHub 提供的 noreply 邮箱;不要通过改写历史提交或关闭身份校验处理。仅网页端登录成功还不代表 CLI 已登录,设备授权页与 CLI 都显示成功后才能使用 CLI 部署。