部署到 Cloudflare Pages

网站只发布docs/.vitepress/dist。不要上传system/.env、数据库、媒体卷或整个源码压缩包到公开静态目录。这里的Pages不运行教材后端。

构建配置

项目	值
仓库根目录	本交付包根目录（含package.json）
Node.js	22（`.node-version`）；本次本地构建版本见验收报告
安装	`npm ci`，使用package-lock.json
构建命令	`npm run docs:build`
输出目录	`docs/.vitepress/dist`
框架	VitePress 1.6.4
环境密钥	文档站不需要任何模型/API密钥
路径	base默认为`/`；cleanUrls=true

本地验证：

bash

npm ci
npm run docs:build
npm run check:links
npm run docs:preview

不要通过file://双击index.html判断网站是否可用：搜索索引与路由需要HTTP服务。构建产物已包含在压缩包中，可直接用于静态部署。

首次部署：Git集成

将源码推送至自己的GitHub/GitLab仓库，保持.env不被跟踪。
在Cloudflare控制台创建Pages项目，选择该仓库。
填入上表构建命令与输出目录，生产分支按仓库选择。
完成部署后访问Cloudflare返回的pages.dev网址。
检查首页、深层章节刷新、导航、搜索“LangGraph”和中文“局部修订”、移动端目录、Mermaid图。

首次部署：直接上传

也可以把已构建的docs/.vitepress/dist通过Pages Direct Upload上传。当前目录已提供一键脚本，先完成 Wrangler 登录，再执行：

bash

npx wrangler login
npm run deploy:pages

脚本会执行以下步骤：

运行npm run docs:build。
从wrangler.toml读取Pages项目名和输出目录。
调用npx wrangler@latest pages deploy发布完整构建产物。

默认项目名为hanlink-agent-interview。如需覆盖项目名，设置CF_PAGES_PROJECT；如需只检查构建和最终命令，可执行npm run deploy:pages -- --dry-run。首次使用时，如果该Pages项目尚未创建，Wrangler可能要求先在Cloudflare控制台创建同名项目；项目创建后即可重复执行脚本。

更新与回滚

Git集成：提交文档和锁文件后推送，检查新构建日志及预览部署，再发布生产分支。直接上传：重新执行锁定依赖构建、内部链接检查，然后上传完整新dist。不要只替换HTML而遗漏带hash的JS和搜索索引。

部署失败先看Node版本、npm ci锁文件一致性、输出路径和VitePress死链接错误。发布成功后从Pages部署历史选择已知良好版本进行回滚；回滚文档站不回滚教材数据库。

本次范围与官方依据

已交付源码、锁文件、构建产物和配置说明。没有连接用户Cloudflare账号，未创建Cloudflare Pages项目，也没有可声称已部署的pages.dev地址。

核验日期2026-11-03。控制台名称可能调整；以上配置以交付的VitePress版本和实际构建目录为准。

部署到 Cloudflare Pages ​

构建配置 ​

首次部署：Git集成 ​

首次部署：直接上传 ​