部署与构建
Fumadocs 部署手册
从本地构建到 GitHub 推送、Vercel 预览部署、正式上线和回滚的执行步骤。
目的
确保 ReBot 内部手册可以在本地稳定运行，并通过 GitHub 和 Vercel 完成可审查、可预览、可回滚的部署流程。
技术栈
| 技术 | 用途 |
|---|---|
| Next.js | 应用框架和 App Router |
| Fumadocs | 文档站点 UI 和 MDX 内容加载 |
| Tailwind CSS | 基础样式 |
| GitHub | 私有仓库、PR、版本记录 |
| Vercel | 预览部署和正式部署 |
本地运行
npm install
npm run dev默认本地地址：
http://localhost:3000/docs本地检查
每次提交前运行：
npm run lint
npm run typecheck
npm run build通过标准：
- 没有 ESLint 错误。
- TypeScript 类型检查通过。
- Next.js production build 成功。
/docs页面可以打开。
GitHub 首次推送
首次创建仓库时建议使用私有仓库：
git init
git add .
git commit -m "feat: initialize rebot handbook"
gh repo create ReBotMono --private --source=. --remote=origin --push如果远程仓库已经存在，改为添加现有 remote：
git remote add origin https://github.com/lintheyoung/ReBotMono.git
git push -u origin mainVercel 预览部署
首次部署建议先创建 Preview Deployment：
npx vercel@latest --yes部署后检查：
- Vercel CLI 输出了 Preview URL。
- Preview URL 可以打开。
/docs页面可以访问。- 页面导航、搜索入口和正文渲染正常。
访问控制
内部手册建议默认保持私有访问。
| 方式 | 适用场景 | 说明 |
|---|---|---|
| GitHub 私有仓库 | 控制谁能看源代码和提交文档 | 邀请成员加入 GitHub 仓库或组织 |
| Vercel Authentication | 控制谁能访问 Vercel 部署页面 | 需要访问者登录 Vercel，并拥有项目访问权限 |
| Vercel Password Protection | 给外部协作者临时访问 | 需要 Pro 付费加购或 Enterprise |
| Vercel Trusted IPs | 只允许固定办公网络访问 | Enterprise 功能 |
| 应用内登录 | 需要更细的账号、角色和邀请机制 | 需要额外接入认证系统，例如 Auth.js、Clerk 或自建登录 |
当前项目的 Vercel Preview 使用 Deployment Protection。没有权限的人打开 Preview URL 时，可能会跳转到 Vercel 登录页。
如果要让同事访问：
- 将同事加入 GitHub 私有仓库。
- 将同事加入 Vercel 项目或团队。
- 让同事使用 Vercel 登录后访问 Preview URL。
- 如果需要外部人员无需 Vercel 账号访问，评估是否开启 Password Protection 或实现应用内登录。
不要为了临时分享而关闭 Deployment Protection，除非负责人明确确认风险。
正式上线流程
创建分支
↓
修改文档
↓
提交 PR
↓
查看 Vercel Preview
↓
负责人 Review
↓
合并 main
↓
Vercel 自动部署正式版本
↓
检查正式站点回滚流程
找到对应 PR 或 commit
↓
确认问题范围
↓
优先 revert commit
↓
提交修复 PR
↓
Vercel 重新部署
↓
检查正式站点检查清单
- 已确认本地
npm run build通过。 - 已确认没有泄露密钥、Token、密码或客户隐私。
- 已提交 Pull Request。
- 已检查 Vercel Preview URL。
- 已由负责人 Review。
- 合并后已检查正式站点。
最近更新
- 2026-05-29：建立 Fumadocs 部署手册初版。