VuePress v2 + GitHub Pages 博客搭建完整指南

本指南涵盖从项目初始化、主题配置、多级侧边栏与导航栏的正确写法、样式定制到 GitHub Actions 自动部署的全流程。所有示例均使用抽象的文件名和占位符，便于直接替换为自己的内容。

一、环境准备

Node.js：v20+（本地与 CI 环境一致）。
Git：用于版本控制与推送。
GitHub 账号：代码托管于主分支（如 master/main），静态站点部署到 gh-pages 分支。
仓库类型：
- 用户站点：仓库名为 用户名.github.io → base: '/'
- 项目站点：仓库名自定 → base: '/仓库名/'

二、项目创建与依赖安装

mkdir my-blog && cd my-blog
npm init -y
npm install -D vuepress@next @vuepress/theme-default@next --legacy-peer-deps
npm install -D sass-embedded --legacy-peer-deps   # 若需要样式预处理

--legacy-peer-deps 用于解决 RC 阶段的依赖版本冲突。

三、目录结构（抽象示例）

my-blog
├── docs
│   ├── .vuepress
│   │   ├── config.js
│   │   ├── public
│   │   │   ├── favicon.ico
│   │   │   └── .nojekyll          # 务必添加
│   │   └── styles
│   │       └── index.scss         # 自定义样式
│   ├── README.md                  # 首页
│   └── 文章目录
│       └── 分类A
│       │   ├── 文章1.md
│       │   └── 文章2.md
│       └── 分类B
│           └── 文章3.md
├── .github
│   └── workflows
│       └── deploy.yml
├── package.json
└── node_modules

四、核心配置文件 `config.js`

所有主题相关设置必须放在 defaultTheme({}) 内部。

import { defineUserConfig } from 'vuepress'
import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'

export default defineUserConfig({
  bundler: viteBundler(),
  base: '/',
  lang: 'zh-CN',
  title: '我的博客',
  description: '记录与分享',
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]],

  theme: defaultTheme({
    logo: '/favicon.ico',
    navbar: [
      { text: '首页', link: '/' },
      {
        text: '文章分类',
        children: [
          { text: '分类A', link: '/文章目录/分类A/文章1.md' },
          { text: '分类B', link: '/文章目录/分类B/文章3.md' },
        ],
      },
      { text: '外部链接', link: 'https://example.com' },
    ],
    sidebar: {
      '/文章目录/': [
        {
          text: '一级分组标题',
          collapsible: true,
          prefix: '分类A/',
          children: [
            {
              text: '二级分组A',
              prefix: '子目录1/',
              children: ['文章1.md', '文章2.md']
            },
            {
              text: '二级分组B',
              prefix: '子目录2',
              children: [
                { text: '自定义标题', link: '某文件.md' }
              ]
            }
          ]
        },
        {
          text: '另一个一级分组',
          collapsible: true,
          prefix: '分类B/',
          children: ['文章3.md']
        }
      ]
    },
    editLink: false,
    lastUpdated: true,
  }),
})

侧边栏路径计算规则

基础路径 = docs/ + 侧边栏 key（如 /文章目录/）
一级分组 prefix 会附加到基础路径后
二级分组 prefix 再附加（末尾有无斜杠决定是目录还是前缀）
最终文件 = 以上路径 + link 或字符串值
示例：若 key 为 /文章目录/，一级前缀 分类A/，二级前缀 子目录1/，字符串 文章1.md → 文件为 docs/文章目录/分类A/子目录1/文章1.md

五、首页 Markdown（`README.md`）

---
home: true
heroText: 我的博客
tagline: 学习·记录·分享
actions:
  - text: 进入文章
    link: /文章目录/
    type: primary
features:
  - title: 前端技术
    details: |
      HTML, CSS, JavaScript
      Vue, React
  - title: 后端技术
    details: |
      Node.js, Python
      数据库与运维
footer: MIT Licensed | Copyright © 2024
---

多行 details 需配合 CSS：.feature .details { white-space: pre-line; }。

六、自定义样式（`index.scss`）

// 侧边栏分组标题加粗
.sidebar-heading {
  font-weight: bold;
}

// 嵌套分组缩进与颜色
.sidebar-group .sidebar-group .sidebar-heading {
  padding-left: 1.5rem;
  color: #2c3e50;
}

// 当前激活页面高亮
.sidebar-item.active .sidebar-link {
  font-weight: bold;
  color: #3eaf7c;
}

修改后需重启 npm run dev 或清理缓存。

七、本地开发命令

在 package.json 的 scripts 中添加：

"dev": "vuepress dev docs",
"build": "vuepress build docs"

运行 npm run dev，访问 http://localhost:8080 预览。

八、GitHub Actions 自动部署

1. 添加 `.nojekyll` 文件

在 docs/.vuepress/public/ 下创建空白文件 .nojekyll，避免 Jekyll 干扰。

2. 创建工作流 `.github/workflows/deploy.yml`

name: Deploy VuePress site to Pages

on:
  push:
    branches: [master]  # 或 main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci --legacy-peer-deps

      - name: Build site
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages
          folder: docs/.vuepress/dist

3. 推送代码

git init
git add .
git commit -m "初始化博客"
git remote add origin 你的仓库地址
git push -u origin master

4. GitHub Pages 设置

仓库 Settings → Pages：

Source：Deploy from a branch
Branch：gh-pages、/(root)
若下拉无 gh-pages，先确保 Actions 成功运行一次。

九、常见问题速查

现象	原因	解决
依赖冲突 `ERESOLVE`	VuePress RC 版本 peer 不一致	安装时加 `--legacy-peer-deps`
缺少 `sass-embedded`	默认主题需 SCSS 预处理	`npm install -D sass-embedded --legacy-peer-deps`
导航/侧边栏不显示	配置未放入 `defaultTheme()`，或路径匹配错误	将主题配置移入 `defaultTheme({})`，检查侧边栏 key 是否匹配当前页面路径
页面样式丢失、资源 404	`base` 设置错误，或未添加 `.nojekyll`	用户站点 `base: '/'`，项目站点 `base: '/仓库名/'`，并添加 `.nojekyll`
Liquid 模板错误	GitHub Pages 用 Jekyll 处理了 Markdown	确保部署源为 `gh-pages` 分支，且包含 `.nojekyll`
构建报正则错误	Node.js 版本低于 20	将 Actions 中 `node-version` 设为 `20`
推送权限拒绝	本地凭据不匹配	更新凭据或改用 SSH

十、总结

以上搭建方式实现了：

基于目录的多级文章分类，侧边栏自动按路径加载。
导航栏下拉菜单快速跳转各分类。
一键部署：推送源代码即自动构建并发布到 GitHub Pages。

后续只需在对应文件夹中添加 Markdown 文件，更新侧边栏配置中的 children 列表，提交推送即可完成内容更新。