部署

Typematter 当前走的是 Next.js 静态导出 路线，npm run build 后会输出完整静态站到 out/。

推荐的仓库模型

Typematter 官方仓库更适合作为：

• 官方文档站
• 在线 demo
• 组件与能力展示仓库

在实际采用时，建议为每个团队或产品生成独立文档仓库，而不是直接在官方仓库里继续编写业务文档。这样可以避免把官方示例、演示内容和业务内容混在一起，也更方便独立维护配置、内容和发布流程。

从官方仓库生成独立项目

1. 克隆官方 Typematter 仓库。

2. 在仓库外执行 npm run typematter -- init --dir ../my-docs。

3. 进入新目录后运行 npm install、npm run dev。

4. 用自己的内容替换 content/，再按实际信息架构修改 site.config.ts 和 nav.config.ts。

构建前需要哪些环境变量

必填：

• TYPEMATTER_SITE_URL=https://docs.example.com

可选但推荐：

• NEXT_PUBLIC_SITE_URL=https://docs.example.com
• NEXT_PUBLIC_TYPEMATTER_ASK_AI_ENDPOINT=https://<your-worker-domain>
• NEXT_PUBLIC_TYPEMATTER_ASK_AI_TIMEOUT_MS=25000
• NEXT_PUBLIC_TYPEMATTER_ASK_AI_ENABLED=true

生产部署步骤

1. 复制 .env.example，填写站点域名和可选的 Ask AI 变量。

2. 执行 npm run validate:docs，先确认内容、导航和链接全部通过校验。

3. 执行 npm run build，生成静态站点与搜索产物。

4. 将 out/ 目录部署到静态托管平台。

构建后会产出什么

• out/：最终静态站点
• .typematter/registry.json：内容 registry 缓存
• public/typematter/search/：搜索清单、文档索引、分片
• public/robots.txt
• public/sitemap.xml

适合的托管目标

• Vercel

  直接构建并发布静态输出目录。

• Cloudflare Pages

  适合全球边缘静态分发。

• Nginx / OSS / S3

  只要能托管 HTML、CSS、JS 即可。

Vercel

• Build Command: npm run build
• Output Directory: out
• Environment Variables: 至少配置 TYPEMATTER_SITE_URL

Cloudflare Pages

• Build Command: npm run build
• Build Output Directory: out
• 如果启用 Ask AI，再单独部署 integrations/cloudflare-ask-ai-worker/

Nginx / OSS / S3

• 直接上传 out/ 目录
• 保持静态文件原样分发
• 若使用自建 Nginx，可将站点根目录直接指向 out/

本地预览构建产物

npm run buildnpx serve out

Ask AI 是额外步骤，不影响静态部署

静态站点本身不依赖 Worker。只有在需要启用 Ask AI 时，才需要继续配置：

• integrations/cloudflare-ask-ai-worker/README.md
• NEXT_PUBLIC_TYPEMATTER_ASK_AI_ENDPOINT

常见问题

为什么 robots.txt / sitemap.xml 里还是 example.com

因为构建时没有设置 TYPEMATTER_SITE_URL。

为什么构建时报 orphan page / broken link

因为 Typematter 会在构建前执行文档质量校验。先运行 npm run validate:docs，再根据报错修正文档结构、导航或链接。

需要一个不包含官方内容的干净项目

不要直接在官方仓库里继续编写业务文档；使用 npm run typematter -- init --dir ../my-docs 生成独立 starter 项目。