维护指南
本指南教你如何维护和更新这个文档站。
📝 日常维护（90% 的工作）
修改现有文档
直接编辑 .md 文件即可，和写笔记一样简单：
docs/
├── go/
│ ├── quick-start.md ← 直接编辑
│ ├── basics.md
│ └── concurrency.md
└── js/
├── quick-start.md ← 直接编辑
├── basics.md
└── es6.md
本地预览（可选）：
bash
pnpm dev
# 访问 http://localhost:5173，保存文件后自动刷新
➕ 添加新文档页面
在现有目录下创建新的 .md 文件，然后在 config.ts 中添加链接。
示例：在 Go 分类下添加「错误处理」页面
1. 创建文件
创建 docs/go/error-handling.md：
markdown
# Go 错误处理
Go 使用显式错误处理而不是异常机制。
## 基本错误处理
\`\`\`go
file, err := os.Open("test.txt")
if err != nil {
log.Fatal(err)
}
defer file.Close()
\`\`\`
2. 更新配置
编辑 docs/.vitepress/config.ts，在 Go 的 items 数组中添加：
typescript
sidebar: [
{
text: 'Go',
items: [
{ text: '快速开始', link: '/go/quick-start' },
{ text: '基础语法', link: '/go/basics' },
{ text: '并发编程', link: '/go/concurrency' },
{ text: '错误处理', link: '/go/error-handling' } // ← 新增
]
},
// ...
]
完成！ 刷新页面即可看到新文档。
🆕 添加新技术分类
添加全新的技术分类（如 Python、Rust）需要两步。
1. 创建目录和文档
docs/
└── python/ ← 新建目录
├── quick-start.md ← 快速开始
├── basics.md ← 基础语法
└── advanced.md ← 高级特性
创建 docs/python/quick-start.md：
markdown
# Python 快速开始
欢迎来到 Python 快速入门教程！
## 安装 Python
\`\`\`bash
python --version
pip --version
\`\`\`
## Hello World
\`\`\`python
print("Hello, 世界！")
\`\`\`
2. 更新 config.ts
编辑 docs/.vitepress/config.ts：
a) 在顶部导航添加入口：
typescript
nav: [
{ text: '首页', link: '/' },
{ text: 'Go', link: '/go/quick-start' },
{ text: 'JavaScript', link: '/js/quick-start' },
{ text: 'Python', link: '/python/quick-start' } // ← 新增
],
b) 在侧边栏添加分组：
typescript
sidebar: [
{
text: 'Go',
items: [
{ text: '快速开始', link: '/go/quick-start' },
{ text: '基础语法', link: '/go/basics' },
{ text: '并发编程', link: '/go/concurrency' }
]
},
{
text: 'JavaScript',
items: [
{ text: '快速开始', link: '/js/quick-start' },
{ text: '基础语法', link: '/js/basics' },
{ text: 'ES6+ 特性', link: '/js/es6' }
]
},
{ // ← 新增整个对象
text: 'Python',
items: [
{ text: '快速开始', link: '/python/quick-start' },
{ text: '基础语法', link: '/python/basics' },
{ text: '高级特性', link: '/python/advanced' }
]
}
],
完成！ 刷新页面，左侧导航会出现 Python 分类。
🚀 部署到 Cloudflare Pages
首次部署
bash
# 1. 构建项目
cd C:\Users\xx\Desktop\Docs\vitepress-project
pnpm build
# 2. 部署到 Cloudflare（首次需要加 --branch=main）
wrangler pages deploy docs\.vitepress\dist --project-name=my-docs --branch=main
部署成功后会返回网站 URL，如：https://my-docs.pages.dev
后续更新部署
每次修改文档后：
bash
# 重新构建
pnpm build
# 重新部署
wrangler pages deploy docs\.vitepress\dist --project-name=my-docs
一键部署脚本（推荐）
使用 deploy.bat：修改文档后，双击项目根目录的 deploy.bat 即可自动构建并部署。
脚本会自动：
- 构建项目（
pnpm build） - 部署到 Cloudflare
- 显示结果
🌐 部署后内容没更新？
这是浏览器缓存导致的，非常常见。
解决方法
强制刷新浏览器：
- Windows:
Ctrl + Shift + R或Ctrl + F5 - Mac:
Cmd + Shift + R
或使用无痕模式验证：
- Windows:
Ctrl + Shift + N - Mac:
Cmd + Shift + N
域名说明
- 主域名：
https://my-docs.pages.dev（固定不变） - 每次部署会生成唯一的预览 URL，但主域名始终指向最新版本
- 分享给别人永远用主域名即可
📂 项目结构
vitepress-project/
├── docs/ # 所有文档内容
│ ├── .vitepress/
│ │ └── config.ts # ⚠️ 配置文件（添加新分类时修改）
│ ├── go/
│ │ ├── quick-start.md
│ │ ├── basics.md
│ │ └── concurrency.md
│ ├── js/
│ │ ├── quick-start.md
│ │ ├── basics.md
│ │ └── es6.md
│ ├── guide.md # 本维护指南
│ └── index.md # 首页
├── deploy.bat # 一键部署脚本
├── package.json
└── README.md # 详细版维护文档
🛠️ 本地开发命令
bash
# 安装依赖（仅首次）
pnpm install
# 启动开发服务器（实时预览）
pnpm dev
# 构建生产版本
pnpm build
# 预览构建结果
pnpm serve
❓ 常见问题
Q: 修改文档后本地看不到效果？
A: 确保开发服务器正在运行：
bash
pnpm dev
保存文件后浏览器会自动刷新。
Q: 新增页面后侧边栏没显示？
A: 检查 config.ts 中是否添加了对应的 link 配置。
Q: 如何修改网站标题？
A: 编辑 docs/.vitepress/config.ts：
typescript
export default defineConfig({
title: '我的技术文档', // ← 修改这里
description: '个人学习笔记',
// ...
})
Q: 如何删除不需要的页面？
A:
- 删除对应的
.md文件 - 在
config.ts中移除对应的链接配置
🎯 快速工作流程
- 编辑文档 → 修改
.md文件 - 本地预览（可选）→
pnpm dev - 部署更新 → 双击
deploy.bat
就这么简单！ 99% 的时间你只需要写 Markdown。