Cloudflare Pages 部署文档站
文档站使用 VitePress 1，部署目标为 Cloudflare Pages，项目名称为 xi-mail-docs。
本地开发
在仓库根目录执行：
cd docs
npm ci
npm run docs:devdocs:dev 和 docs:build 会先读取仓库中的 README、界面预览、集成说明和子 Worker README，生成文档页面并复制公开图片及插件下载文件。修改这些原始文件后重新运行命令即可同步。
首页及文档站维护说明在 docs/src/，导航与搜索配置在 docs/.vitepress/config.mjs。.generated/ 是构建时生成的目录，不要直接编辑。
构建与预览
npm run docs:build
npm run docs:preview输出目录为 docs/.vitepress/dist（相对于仓库根目录）。站点部署到域名根路径，base 使用默认的 /。
直接上传到 Cloudflare Pages
首次部署，先在 docs 目录登录并创建 Pages 项目：
npx wrangler login
npx wrangler pages project create xi-mail-docs --production-branch main --forceWrangler 4.162 创建新项目时默认转向 Workers；首次创建加 --force 以明确使用本指南的 Pages 部署方式。项目已存在时跳过创建步骤，后续发布无需此参数。
之后每次发布，在 docs 目录执行：
npm run docs:deploy命令会先构建，再通过 wrangler.jsonc 将 .vitepress/dist 上传到 xi-mail-docs 项目的 main 生产分支。实际访问地址以 Wrangler 输出为准。
使用 Git 自动构建
如果需要由 Git 推送触发发布，可另建一个连接 Git 的 Cloudflare Pages 项目，配置如下：
| 设置 | 值 |
|---|---|
| 根目录 | docs |
| 构建命令 | npm run docs:build |
| 构建输出目录 | .vitepress/dist |
| Node.js | 22 |
| 生产分支 | main |
构建会读取仓库其他目录中的公开文档，因此提交时须保留完整仓库结构。当前仓库根 .gitignore 忽略了 docs；使用 Git 自动构建前，需要自行取消该规则并提交文档项目。
Cloudflare 的 Direct Upload 项目无法直接切换为 Git 集成；需要新建对应类型的项目。参见 Cloudflare Direct Upload。
绑定自定义域名
在 Cloudflare 控制台打开 Workers & Pages → xi-mail-docs → Custom domains，添加需要使用的文档域名，并按提示完成 DNS 设置。