主题
文档站部署说明
本页用于说明这套指南当前如何进行本地预览、静态构建，以及后续如何接入线上托管。
1. 本地预览
安装依赖
bash
npm install启动开发预览
bash
npm run docs:dev默认会启动 VitePress 本地服务，适合你继续调首页、导航、样式和内容结构。
2. 静态构建
构建站点
bash
npm run docs:build构建成功后，静态产物会输出到：
text
docs/.vitepress/dist/本地预览构建结果
bash
npm run docs:preview3. 站点配置入口
如果你需要继续调整站点结构，优先看下面几个文件：
- VitePress 主配置：
docs/.vitepress/config.ts - 主题入口：
docs/.vitepress/theme/index.ts - 首页样式：
docs/.vitepress/theme/custom.css - 中立导航配置：
docs/site-navigation.json - 人类可读侧边栏
- 框架配置草案：
docs/site-configs/README.md
4. 静态托管建议
当前这套文档站本质上是标准静态站点，因此可以部署到：
- GitHub Pages
- Vercel
- Netlify
- 任意支持静态文件托管的对象存储 / CDN
部署时只需要把 docs/.vitepress/dist/ 目录作为发布产物即可。
5. GitHub Pages 最小思路
想通过网页访问？ 只需在 GitHub 仓库里做一件事：Settings → Pages → Source 选 “GitHub Actions”。
推送代码到 main 后会自动部署，访问地址为：https://你的用户名.github.io/ai-agent-guide/（项目仓库）。
详细步骤见 GitHub Pages 部署说明 第 0 节。
如果后续你准备接 GitHub Pages，建议流程是：
- 在 CI 中执行
npm install - 执行
npm run docs:build - 把
docs/.vitepress/dist/发布到 Pages
当前仓库已补：
- Workflow 示例：
docs/site-configs/github-pages-workflow.yml.example - 配套说明
- 真实 workflow：
.github/workflows/deploy-docs.yml - 自建服务器部署：仓库内
scripts/README-deploy-server.md，推荐域名agent.daozishule.cn
6. Vercel 最小思路
如果你更偏向零配置托管，也可以选择 Vercel。 当前仓库已补：
- 配置示例：
docs/site-configs/vercel.json.example
最小思路是：
- 安装依赖：
npm install - 构建站点：
npm run docs:build - 输出目录指向：
docs/.vitepress/dist/
7. Netlify 最小思路
如果你希望使用传统静态站托管平台，也可以选择 Netlify。 当前仓库已补：
- 配置示例：
docs/site-configs/netlify.toml.example
最小思路是：
- 安装依赖：
npm install - 构建站点：
npm run docs:build - 发布目录：
docs/.vitepress/dist/
8. GitHub Pages 实战说明
当前真实 workflow 会在 CI 中：
- 自动计算
VITEPRESS_BASE - 安装依赖并构建站点
- 把
docs/.vitepress/dist/发布到 GitHub Pages
如果仓库名不是 {owner}.github.io，workflow 会自动把 base 设置为 /{repo}/。
9. 部署后访问路径说明
部署成功后，最常见的访问路径差异来自 base：
- 如果你部署的是个人主页仓库（如
{owner}.github.io），通常访问根路径/。 - 如果你部署的是项目仓库（如
repo-name），GitHub Pages 常见访问路径会变成/{repo-name}/。 - 当前仓库的真实 workflow 会自动注入
VITEPRESS_BASE，尽量减少这类手工配置错误。 - 如果你换成 Vercel 或 Netlify，通常可以直接使用根路径
/，但若你做了二级路径托管，仍需同步调整base。
10. 当前状态
当前仓库已验证：
npm install可完成依赖安装npm run docs:build可成功构建站点- 站点首页、侧边栏、样章、专题、项目线、附录、示例和组件都能参与构建
- SEO：已配置 sitemap.xml、robots.txt、每页 canonical、Open Graph / Twitter meta；默认站点 URL 为
https://agent.daozishule.cn，部署到 GitHub Pages 时请设置环境变量VITEPRESS_SITE_URL为实际域名（如https://你的用户名.github.io）并在 build 时传入VITEPRESS_BASE。
11. 推荐下一步
如果你准备继续把它做成真正线上站点，建议按这个顺序推进：
- 固定域名和部署目标
- 补 GitHub Actions 或其他 CI workflow
- 增加真实截图与配图
- 继续细化首页视觉层与站点导航体验