文档站单独部署

WeMail 文档站位于：

apps/docs

它在 monorepo 里维护，但可以作为独立站点部署。推荐直接部署到 Vercel：

当前技术栈：

本地启动

在仓库根目录执行：

pnpm dev:docs

默认地址：

http://127.0.0.1:3000

只验证文档站：

pnpm lint:docs
pnpm typecheck:docs
pnpm build:docs

内容目录

文档页面在：

apps/docs/content/docs

新增一篇文档时，创建 MDX 文件：

apps/docs/content/docs/new-page.mdx

基础 frontmatter：

---
title: 页面标题
description: 页面说明
---

正文内容

侧边栏顺序由：

apps/docs/content/docs/meta.json

控制。

图片资源

文档图片建议放在：

apps/docs/public/docs/screenshots

在 MDX 中引用：

![截图说明](/docs/screenshots/local-dev-terminal.png)

不要在文档里引用本机临时路径，例如 /var/folders/...，部署后会失效。

推荐部署方式：Vercel

Next.js + Fumadocs 的最省心部署目标是 Vercel。

一键部署

点击上方 Deploy with Vercel 按钮后，Vercel 会从 GitHub 克隆仓库并预填：

NEXT_PUBLIC_SITE_URL 填文档站最终公开访问地址，例如：

https://docs.example.com

如果暂时没有正式域名，可以先填 Vercel 分配的 production 域名，后续绑定自定义域名后再更新。

方案 A：Vercel Git 集成，推荐

Root Directory 设为 apps/docs 后，Vercel 会在文档站目录内安装和构建，并自动读取 apps/docs/package.json 里的 build 脚本，也就是执行等价于 pnpm run build 的命令。

不要在这个方案里填写 pnpm build:docs。这个脚本只存在仓库根目录；当 Vercel 已经进入 apps/docs 后再执行它，会因为找不到脚本而构建失败。

需要绑定正式域名时，在 Vercel 项目的 Settings -> Environment Variables 添加：

NEXT_PUBLIC_SITE_URL=https://docs.example.com

方案 B：仓库根目录构建

如果项目的 Root Directory 保持为仓库根目录，才使用根目录脚本：

这个方案适合需要从 monorepo 根目录统一管理构建命令的团队。日常部署文档站时，优先使用方案 A。

Cloudflare 部署说明

Cloudflare Pages 对普通静态站点很友好，但当前 docs app 是 Next.js 16 应用，不是纯静态导出配置。

如果要部署到 Cloudflare，建议走其中一种：

1. 使用 OpenNext / Cloudflare Workers 方案承载 Next.js。
2. 评估是否把文档站改为可静态导出，再部署到 Pages。

在没有完成这一步前，不建议直接把 .next 当作静态目录上传到 Pages。

自定义域名

建议使用独立域名：

docs.example.com

这样文档站和产品站可以独立发布，也不会影响 WeMail 主应用的 /api/* 路由策略。

发布前检查

• pnpm lint:docs 通过。
• pnpm typecheck:docs 通过。
• pnpm build:docs 通过。
• 新增图片位于 apps/docs/public。
• 新增页面已加入 meta.json。
• 首页卡片或相关文档能链接到新页面。
• 没有把真实 secret、Cloudflare token、私有账号 ID 写进文档。

文档维护约定

• 部署流程变化时，同步更新产品部署文档和根 README。
• Cloudflare 控制台截图如果来自真实账号，先遮挡账号 ID、邮箱、token 和域名隐私。
• 示例 token 使用占位符，不使用看起来像真实密钥的字符串。
• 每次提交按仓库约定更新根 CHANGELOG.md 的 [Unreleased]。