将本站部署到 Cloudflare

🎯 难度：入门⏱ 预计：15–30 分钟# 纯静态# Cloudflare Pages

本站使用 VitePress 构建，输出只是 HTML + CSS + JavaScript + 本地搜索索引。没有后端、数据库或在线模型请求。动效和学习标记在浏览器运行，不改变它作为静态站点的部署方式。

本地预览

在文档项目根目录运行，不是 Python 练习目录：

npm ci
npm run dev

构建并预览生产版：

npm run build
npm run preview

构建产物：docs/.vitepress/dist。不要部署源码目录、node_modules 或 Python .venv。

本地校验

npm run check

会构建全部页面、检查站内链接与搜索索引，并检查课程前端脚本语法。

可选的 Python 示例检查（需要 uv，与静态网站构建无关）：

uv run --python 3.12 \
  --with "openai>=1.68,<2" --with "python-dotenv>=1,<2" \
  --with "mcp==1.12.4" --with "pydantic==2.11.7" \
  --with "pydantic-settings==2.10.1" --with "fastapi>=0.115,<1" \
  scripts/check_examples.py

它使用合成数据做工具循环、路径、检索和流式协议测试，并与本地 MCP 子进程进行握手，不调用付费 API。测试产物在忽略的 .verify/ 目录。真实模型输出仍需你配置 Key 后按各项目验收步骤验证。

方式一：Cloudflare Pages 连接 Git 仓库

推荐用于长期维护，提交内容后自动构建。你需要先自行创建 Git 仓库并上传本项目。

1. 在 Cloudflare 控制台进入 Workers & Pages。
2. 创建 Pages 项目，选择导入 Git 仓库（界面名称可能随版本调整）。
3. 选择本项目仓库与生产分支。
4. 使用以下配置，不要照抄根目录版 VitePress 模板的默认值：

配置	本项目的值
Framework preset	VitePress 或 None，手动填写下面两项
Build command	npm run build
Build output directory	docs/.vitepress/dist
Root directory	仓库根目录，留空即可
环境变量	NODE_VERSION=22

这个网站不需要模型 API Key。不要把课程练习的 .env、私有笔记或知识库索引上传到 Pages。

保存并部署，Cloudflare 会提供 *.pages.dev 地址。之后可以在项目的 Custom domains 中添加自己的域名，按控制台要求配置 DNS。

方式二：本地构建，直接上传

先构建：

npm run build

你可以在 Pages 的 Direct Upload 流程中上传 docs/.vitepress/dist 里的内容。

或者使用 Wrangler CLI。下面命令会登录/创建云项目/发布静态产物，是你手动执行的部署步骤，本站不会自动执行：

npx wrangler@4 login
npx wrangler@4 pages project create agent-development
npx wrangler@4 pages deploy docs/.vitepress/dist --project-name agent-development

项目已存在时跳过 create；项目名被占用时换成你自己的名称。Direct Upload 与 Git 集成的后续管理方式不同，创建前先选适合你的方式。

项目也提供 npm run deploy 快捷命令，它会先 build，再发布到 agent-development，请确保你已登录且项目存在，并根据需要修改 package.json 中的项目名。

路由和刷新

本站开启 cleanUrls，如 /python/basics，Cloudflare Pages 支持静态 HTML 的无扩展路径。不要添加 SPA 式 /* /index.html 200 重写，它会掩盖真实 404 或把文档路由都导向首页。

部署后手动检查：

• 首页、任意课程页都能打开。
• 直接访问 /agent/from-scratch 并刷新仍能展示内容。
• 搜索可以查到 Python、RAG、MCP 等课程。
• 不存在的 URL 正常显示 404。
• 手机能打开侧边菜单，代码块和表格能横向滚动。

如何更新内容？

• 内容在 docs/ 对应的 Markdown 文件。
• 导航在 docs/.vitepress/config.mts。
• 样式在 docs/.vitepress/theme/custom.css。
• 交互组件在 docs/.vitepress/theme/components/。

提交 package-lock.json，用同一套依赖构建。更新 Markdown 后重新构建，不需要重启后端。

文档站与 Agent 应用的区别

课程中的 Python、FastAPI 和 MCP 服务需要本地或对应运行环境。它们是文档里的练习，不会因为部署了文档就开始在线运行。

文档可以纯静态托管；如果以后想在线提供一个真正可用的 Agent，需另外设计服务端部署、身份认证、配额与安全边界。两者分开维护最清晰。