VuePress 博客搭建与自动部署完全指南

2026/2/1大约 8 分钟...

本文档详细记录了本博客从零搭建、分类管理到实现双重自动部署的全过程。

1. 安装与初始化 (Installation)

1.1 环境准备

确保本地已安装 Node.js (推荐 v20+)。

1.2 初始化项目

本项目使用 VuePress v2。

# 创建并进入目录
mkdir my-blog
cd my-blog

# 初始化 package.json
npm init -y

# 安装 VuePress 及相关依赖
npm install -D vuepress@next @vuepress/client@next @vuepress/theme-default@next

1.3 配置脚本

在 package.json 中添加脚本：

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }
}

2. 使用指南 (Usage)

2.1 目录结构

我们采用了语义化的目录结构,便于管理和 SEO。

.
├── docs
│   ├── .vuepress (配置目录)
│   ├── os        (操作系统分类)
│   │   └── windows
│   │   └── linux
│   ├── tools     (工具分类)
│   ├── guide     (指南分类)
│   └── README.md (首页)
└── package.json

2.2 撰写文章

在 docs 下的相应分类目录中创建 .md 文件。

Frontmatter 示例：

---
title: 我的第一篇文章
date: 2026-02-01
category:
  - OS
tag:
  - Windows
  - Tips
---

2.3 本地预览

npm run dev

访问 http://localhost:8080 查看效果。

2.4 首页配置 (Homepage Configuration)

VuePress Theme Hope 提供了丰富的首页配置选项，可以打造专业美观的首页。

完整配置指南

首页配置的完整说明已移至 Hope 主题配置指南：📖 Hope 主题首页配置

本节仅提供快速入门，详细配置请查看主题配置指南。

2.4.1 快速入门

首页配置在 docs/README.md 的 Frontmatter 中完成：

---
home: true
title: 首页
heroText: 你的站点名称
tagline: 站点标语
heroImage: /assets/images/hero.png

actions:
  - text: 开始阅读 →
    link: /guide/
    type: primary

features:
  - title: 🤖 功能一
    details: 功能描述
    link: /path/
---

2.4.2 两种展示方式

方式一：features（简单列表，推荐）

适合简单的功能列表展示：

features:
  - title: 标题
    details: 描述
    link: 链接

方式二：highlights（高级展示）

适合需要多个章节的复杂展示：

highlights:
  - header: 章节标题
    description: 章节描述
    highlights:
      - title: 标题
        details: 描述

重要提醒

features 和 highlights 只能使用其中一个
图片路径必须是绝对路径（以 / 开头）

2.4.3 配置资源

📄 README.example.md - 完整配置示例（带注释）
📖 Hope 主题首页配置 - 详细配置说明
📖 官方文档 - VuePress Hope 官方文档

3. 主题定制 (Theme Customization)

3.1 主题选择

VuePress 生态提供了多个优秀的主题，每个主题都有其独特的特点和适用场景：

主题	特点	适用场景	详细教程
Theme Hope	功能最丰富，支持博客+文档，Markdown 增强	需要功能完整的站点	配置指南
Theme Plume	响应式布局，博客和文档兼顾，配置简单	注重设计和用户体验	配置指南
Theme Reco	简洁的博客主题，使用 Tailwind CSS	纯博客站点	配置指南
Default Theme	VuePress 官方默认主题，轻量简洁	简单文档站点	官方文档

当前博客使用: Theme Hope ✨

3.2 VuePress 官方资源

官网: https://vuejs.press/
中文文档: https://vuejs.press/zh/
默认主题配置: https://vuejs.press/zh/reference/default-theme/

3.3 深色/浅色模式切换

所有推荐的主题都内置深色模式支持。以 Theme Hope 为例，配置如下：

import { hopeTheme } from 'vuepress-theme-hope'

export default {
  theme: hopeTheme({
    // 主题颜色模式配置
    darkmode: 'switch', // 支持深色模式切换
  }),
}

配置选项说明：

Theme Hope: darkmode: 'switch' / 'toggle' / 'auto' / 'enable' / 'disable'
Default Theme: colorMode: 'auto' + colorModeSwitch: true

更多主题的深色模式配置请参考对应的主题配置指南。

3.4 自定义样式

如需更深度的样式定制，可以在 docs/.vuepress/styles/ 下创建以下文件：

palette.scss: 定义颜色变量（如主题色）
index.scss: 添加自定义 CSS 样式

3.5 搜索功能 (Search)

VuePress Theme Hope 支持多种搜索插件，为博客添加强大的搜索能力。

完整搜索配置指南

完整的搜索配置指南已移至独立文档：📖 搜索功能配置指南

独立文档包含两种搜索方案的详细对比、配置步骤和使用说明：

Slimsearch（本地搜索）：零配置，开箱即用 ✨
Algolia DocSearch（云端搜索）：功能强大，需要申请

快速链接：

📖 搜索方案对比 - 了解两种方案的优缺点
🔧 Slimsearch 配置 - 本地搜索配置（推荐）
☁️ Algolia 配置 - 云端搜索配置

当前博客使用: Algolia DocSearch（云端搜索）

3.6 图片资源配置 (Image Assets)

为了使博客看起来更专业，我们配置了统一的图片资源。

资源路径: docs/.vuepress/public/assets/images/

主要资源清单:

logo.png: 站点 Logo (蓝色/绿色科技主题)
avatar.png: 博主头像 (机甲风格)
hero.png: 首页大图 (全栈开发概念)
bg.png: 首页背景图 (深色科技纹理)
cover.png: 默认文章封面

配置方式:

在 docs/.vuepress/config.js 中引用：

theme: hopeTheme({
  logo: '/assets/images/logo.png',
  blog: {
    avatar: '/assets/images/avatar.png',
  },
})

在 docs/README.md 中引用：

heroImage: /assets/images/hero.png
heroImageDark: /assets/images/hero.png
bgImage: /assets/images/bg.png

3.7 Waline 评论系统与阅读量统计

为博客添加评论系统和文章阅读量统计功能，使用 Waline 一站式解决方案。

完整配置指南

完整的 Waline 配置指南已移至独立文档：📖 Waline 配置指南

独立文档包含详细的部署步骤、配置说明、通知设置、故障排查等完整内容。

Waline 核心功能：

✅ 评论系统 - 支持 Markdown、表情、图片上传
✅ 页面浏览量统计 - 自动统计文章阅读量
✅ 评论管理 - 后台管理评论、审核、邮件通知
✅ 多种通知渠道 - 企业微信、Discord、Telegram 等

快速链接：

📖 完整配置指南 - 查看详细文档
� 部署 Waline 服务 - Neon / LeanCloud 方案
🔧 VuePress 插件配置 - 评论和浏览量配置
🔔 评论通知配置 - 企业微信、Discord、Telegram
❓ 常见问题 - 故障排查指南

推荐方案

推荐使用 Neon PostgreSQL 方案，配置最简单，无需手动设置安全域名。

3.8 更多配置

Waline 还支持更多高级配置，详见官方文档：

评论通知: 邮件/微信/Telegram 通知
多语言支持: 国际化配置
自定义表情: 表情包配置
评论审核: 管理员审核
数据迁移: 从其他评论系统迁移

4. 部署 (Deployment)

本项目实现了 Vercel 和 GitHub Pages (外部仓库) 的双重自动部署。

4.1 Vercel 部署 (推荐)

已配置 vercel.json，只需在 Vercel 后台导入 GitHub 仓库即可。

优点：速度快，配置简单，原生支持私有仓库。
配置文件：vercel.json

4.2 GitHub Pages (私有仓库方案)

由于 GitHub Pages 免费版不支持私有仓库，我们使用 Actions 将构建产物推送到另一个 公开仓库。

工作流配置 (.github/workflows/deploy.yml)：

触发：Push 到 main 分支。
构建：运行 npm run build。
部署：使用 peaceiris/actions-gh-pages 将 docs/.vuepress/dist 推送到指定的外部公开仓库 (例如 isoftos/isoftos.github.io)。

必要设置：

在私有仓库设置 Secret: DEPLOY_TOKEN (值为具有 repo 权限的 PAT)。
确保外部公开仓库已创建。

5. 常见问题 (FAQ)

Q: 为什么文章访问显示 404 或空白？

A: 检查 Frontmatter 格式是否正确，或者文件名是否包含特殊字符。如果是 GitHub Pages，检查 base 路径配置是否与仓库名匹配。

Q: 如何修改侧边栏？

A: 编辑 docs/.vuepress/config.js (或 config.ts) 中的 themeConfig.sidebar。我们通常使用自动生成或手动指定的方式。

Q: 部署失败，提示 "Permission denied to github.com"？

A: 检查 Actions Secrets 中的 DEPLOY_TOKEN 是否过期，或者 Token 是否拥有目标仓库的写入权限。

Q: 推送到 GitHub 后，Vercel 没有自动部署？

A: 最常见的原因是 Vercel 的 Git Integration 触发选项未正确配置。

首先检查（最关键）：

进入 Vercel Dashboard → 你的项目 → Settings → Git，在 Comments 部分确保：

✅ Commit Comments 已启用（这是触发自动部署的关键选项）
如果只勾选了 "PR Comments"，直接推送到主分支不会触发部署

其他可能原因：

Production Branch 配置
- 确认 "Production Branch" 设置的分支与你推送的分支一致（通常是 main）
Ignored Build Step
- 如果配置了构建忽略规则，某些提交可能被跳过
GitHub Webhooks 检查
- GitHub 仓库 → Settings → Webhooks → 查看 Vercel webhook 的 Recent Deliveries
- 如果失败，在 Vercel 中断开并重新连接 Git 仓库
手动触发部署（临时方案）
- Vercel Dashboard → Deployments → Redeploy

Q: 如何切换主题（深色/浅色模式）？

A: 在导航栏右上角点击主题切换按钮 🌙/☀️ 即可。主题默认会根据系统设置自动适配，也可以手动切换。