---
title: Fumadocs 部署手册
description: 从本地构建到 GitHub 推送、Vercel 预览部署、正式上线和回滚的执行步骤。
---

## 目的

确保 ReBot 内部手册可以在本地稳定运行，并通过 GitHub 和 Vercel 完成可审查、可预览、可回滚的部署流程。

## 技术栈

| 技术 | 用途 |
| --- | --- |
| Next.js | 应用框架和 App Router |
| Fumadocs | 文档站点 UI 和 MDX 内容加载 |
| Tailwind CSS | 基础样式 |
| GitHub | 私有仓库、PR、版本记录 |
| Vercel | 预览部署和正式部署 |

## 本地运行

```bash
npm install
npm run dev
```

默认本地地址：

```text
http://localhost:3000/docs
```

## 本地检查

每次提交前运行：

```bash
npm run lint
npm run typecheck
npm run build
```

通过标准：

- 没有 ESLint 错误。
- TypeScript 类型检查通过。
- Next.js production build 成功。
- `/docs` 页面可以打开。

## GitHub 首次推送

首次创建仓库时建议使用私有仓库：

```bash
git init
git add .
git commit -m "feat: initialize rebot handbook"
gh repo create ReBotMono --private --source=. --remote=origin --push
```

如果远程仓库已经存在，改为添加现有 remote：

```bash
git remote add origin https://github.com/lintheyoung/ReBotMono.git
git push -u origin main
```

## Vercel 预览部署

首次部署建议先创建 Preview Deployment：

```bash
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 登录页。

如果要让同事访问：

1. 将同事加入 GitHub 私有仓库。
2. 将同事加入 Vercel 项目或团队。
3. 让同事使用 Vercel 登录后访问 Preview URL。
4. 如果需要外部人员无需 Vercel 账号访问，评估是否开启 Password Protection 或实现应用内登录。

不要为了临时分享而关闭 Deployment Protection，除非负责人明确确认风险。

## 正式上线流程

```text
创建分支
↓
修改文档
↓
提交 PR
↓
查看 Vercel Preview
↓
负责人 Review
↓
合并 main
↓
Vercel 自动部署正式版本
↓
检查正式站点
```

## 回滚流程

```text
找到对应 PR 或 commit
↓
确认问题范围
↓
优先 revert commit
↓
提交修复 PR
↓
Vercel 重新部署
↓
检查正式站点
```

## 检查清单

- [ ] 已确认本地 `npm run build` 通过。
- [ ] 已确认没有泄露密钥、Token、密码或客户隐私。
- [ ] 已提交 Pull Request。
- [ ] 已检查 Vercel Preview URL。
- [ ] 已由负责人 Review。
- [ ] 合并后已检查正式站点。

## 最近更新

- 2026-05-29：建立 Fumadocs 部署手册初版。