Cloudflare 部署

方案一：Cloudflare Pages

在 Cloudflare Dashboard 的 Workers & Pages 中导入 Git 仓库，选择 VitePress 预设并填写：

选项	值
Production branch	main
Build command	npm run docs:build
Build output directory	docs/.vitepress/dist
Node version	20 或更高

每次推送会自动重建；Pull Request 可获得预览部署。自定义域名在项目的 Custom domains 中绑定。

如果站点位于域名根路径，无需环境变量。若部署到子路径，设置：

DOCS_BASE=/your-prefix/

站点默认生产域名为：

DOCS_ORIGIN=https://docs.anibaka.com

wrangler.jsonc 已将 docs.anibaka.com 声明为 Custom Domain。Cloudflare 会自动创建对应 DNS 记录并签发证书；该主机名不能同时存在冲突的 CNAME。

方案二：Workers Static Assets

仓库根目录已经包含：

{
  "name": "anibaka-docs",
  "compatibility_date": "2026-07-18",
  "assets": {
    "directory": "./docs/.vitepress/dist",
    "not_found_handling": "404-page",
    "html_handling": "auto-trailing-slash"
  }
}

首次部署：

npm ci
npx wrangler login
npm run deploy:worker

之后 CI 中只需提供 Cloudflare API Token 与 Account ID，并执行：

npm ci
npm run deploy:worker

纯静态部署不需要 main Worker 入口。匹配的资源由 Workers Static Assets 直接服务，未匹配请求使用构建产物中的最近 404.html。

为什么不是 SPA fallback

VitePress 是静态站点生成器，每条文档路由都有预渲染 HTML。配置使用：

• not_found_handling: "404-page"：保留正确的 404 状态。
• html_handling: "auto-trailing-slash"：自动处理 .html 与目录索引式路由。

不要设置 single-page-application，否则不存在的文档也可能返回首页和 200 状态，影响搜索引擎与错误监控。

自定义域名

Worker 发布后可在 Cloudflare Dashboard 为 Worker 添加 Custom Domain。使用根域时 VitePress base 保持 /。

构建与运行职责

CI / Cloudflare build
  npm ci
  npm run docs:build
       ↓
docs/.vitepress/dist
       ↓
Pages CDN 或 Workers Static Assets

文档站自身没有 API、数据库或运行时 secret。未来若加入动态接口，再单独添加 Worker main 与资产 binding。