02 本地预览

本地预览是指在你的电脑上启动一个开发服务器，让你可以在浏览器中实时查看博客的渲染效果。你对 Markdown 文件、样式文件、配置文件的任何修改，都会实时反应到网页中。

一、启动开发服务器

在项目根目录下，执行以下命令：

pnpm docs:dev

或者更简洁的别名：

pnpm dev

启动成功后，你会看到类似下面的输出：

  vitepress v1.x.x

  ➜  Local:   http://localhost:5173/knowledge/
  ➜  Network: use --host to expose
  ➜  press h to show help

二、在浏览器中查看

在浏览器中打开上面显示的地址，通常是 http://localhost:5173/knowledge/。

💡 注意：由于我们配置了 base: '/knowledge/'，本地开发服务器也会在 /knowledge/ 路径下提供服务，这与最终部署到 GitHub Pages 的路径一致。

实时预览的特点

特点	说明
Markdown 内容修改	保存后页面会自动刷新
样式文件修改	保存后页面会自动刷新
配置文件修改	部分配置需要重启开发服务器才能生效
刷新不及时	可以手动按 Ctrl/Cmd + R 强制刷新

三、停止开发服务器

在运行开发服务器的终端窗口中，按 Ctrl + C 即可停止服务。

四、本地构建（可选）

如果你想在本地模拟线上部署后的效果，可以执行构建命令生成静态页面：

pnpm docs:build

构建完成后，渲染出来的 HTML、CSS、JavaScript 和各种资源将被存储在 .vitepress/dist 目录中。

预览构建结果

执行构建后，可以通过以下命令在本地预览构建产物：

pnpm docs:serve

这会启动一个静态文件服务器，你可以在浏览器中访问以查看最终部署到 GitHub Pages 后的效果。

五、写作与预览工作流

一个典型的写作与预览工作流程如下：

  1. 打开终端，进入项目目录
         │
         ▼
  2. 执行 pnpm docs:dev 启动开发服务器
         │
         ▼
  3. 在浏览器打开 http://localhost:5173/knowledge/
         │
         ▼
  4. 编辑 / 新建 Markdown 文档，保存文件
         │
         ▼
  5. 浏览器自动刷新，查看渲染效果
         │
         ▼
  6. 满意后，commit + push 到 GitHub 的 main 分支
         │
         ▼
  7. GitHub Actions 自动触发部署，线上博客更新

💡 提示：在本地预览满意后再提交并推送，可以避免在部署后发现排版或链接问题而需要反复修改。

六、关于 images 图片路径

由于站点部署在子路径 /knowledge/ 下，引用图片时需要注意：

• Markdown 图片语法：使用相对路径即可，VitePress 会自动处理
• 示例：![说明](./assets/my-image.png)

如果图片显示不正常，请检查：

1. 图片文件是否与 Markdown 文件在同一目录或正确的相对位置
2. 文件路径大小写是否一致（GitHub Pages 区分大小写）