外观
文档部署
文档站通过 Vercel 的 GitHub 集成自动部署。仓库根目录的 vercel.json 固定了安装、构建和产物目录,避免 Vercel 在 monorepo 中误构建后台模板。
首次连接 Vercel
- 在 Vercel 中导入本 GitHub 仓库;
- 将 Root Directory 保持为仓库根目录,不要选择
apps/docs; - 将生产分支设置为
main; - 完成首次部署,并确认 Vercel 读取了根目录的
vercel.json,构建日志执行了pnpm docs:build。
仓库配置如下:
| 配置 | 值 |
|---|---|
| Install Command | pnpm install --frozen-lockfile |
| Build Command | pnpm docs:build |
| Output Directory | apps/docs/.vitepress/dist |
| Clean URLs | true,与 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 Directory | apps/template |
| Framework Preset | Vite |
| Install Command | pnpm install --frozen-lockfile |
| Build Command | pnpm build |
| Output Directory | dist |
| 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。
排查部署没有触发
依次检查:
- Vercel 项目是否仍连接到正确的 GitHub 仓库;
- Vercel 项目的 Git 设置是否启用了目标分支部署;
- Production Branch 是否为
main; - Root Directory 是否为仓库根目录;
- 当前部署是否读取了仓库根目录的
vercel.json; - GitHub commit checks 与 Vercel 构建日志中的具体错误。
若部署状态为 BLOCKED 且提示无法识别提交作者,检查提交邮箱是否与自己的 GitHub 账号关联,并确认 Vercel 登录连接匹配该账号。为后续提交使用该账号已验证的邮箱或 GitHub 提供的 noreply 邮箱;不要通过改写历史提交或关闭身份校验处理。仅网页端登录成功还不代表 CLI 已登录,设备授权页与 CLI 都显示成功后才能使用 CLI 部署。