---

layout: doc title: 使用 VitePress 搭建现代化技术博客：从零配置到 GitHub Pages 自动部署（含自定义域名） categories:

• 博客系统 tags:
• VitePress
• GitHub Pages
• 博客搭建
• 静态网站 lastUpdated: true sidebar: true

---

使用 VitePress 搭建现代化技术博客：从零配置到 GitHub Pages 自动部署（含自定义域名）

本文将带你从零开始，使用 VitePress 构建高性能静态博客，实现 源码私有 + 自动部署 + 自定义域名 + HTTPS 的完整工作流。涵盖环境准备、项目初始化、内容编写、本地预览、CI/CD 配置、DNS 设置及常见问题排查，适合希望打造专业个人博客的开发者。

---

🎯 一、整体架构设计

我们采用 “源码与发布分离” 的经典模式：

仓库类型	用途说明
源码仓库	私有仓库（如 my-blog-source），存放 VitePress 源码、Markdown、配置等
发布仓库	公开仓库 username/username.github.io，托管构建后的静态文件
自定义域名	如 example.com，通过 DNS 指向 GitHub Pages，提升专业形象

✅ 优势：代码隐私安全、部署自动化、访问体验专业。

---

🔧 二、前置准备

1. 环境要求

确保已安装：

node -v  # ≥ 18.0（推荐 20 LTS）
git --version

若未安装，请前往 Node.js 官网 下载 LTS 版本。

2. 仓库创建

• 在 GitHub 创建私有仓库：my-blog-source
• 确保已存在公开仓库：https://github.com/username/username.github.io（若无，新建即可）

---

🚀 三、初始化 VitePress 项目

1. 克隆并初始化

git clone https://github.com/username/my-blog-source.git
cd my-blog-source

npm init -y
npm install vitepress --save-dev
npx vitepress init

按提示选择：

• Config directory: docs
• Site title: 技术博客
• Theme: Default
• Add example page: Yes

生成结构如下：

my-blog-source/
├─ docs/
│  ├─ .vitepress/
│  │  ├─ config.mts     # 核心配置
│  │  └─ public/        # 静态资源（含 CNAME）
│  ├─ index.md          # 首页
│  └─ posts/            # 博客文章目录
├─ package.json
└─ .github/workflows/deploy.yml  # 后续添加

---

⚙️ 四、核心配置（docs/.vitepress/config.mts）

import { defineConfig } from 'vitepress'
import fs from 'fs'

export default defineConfig({
  // 1. 基础配置（部署到根域名必须为 '/'）
  base: '/',
  title: '技术博客',
  description: '个人技术分享与成长记录',

  // 2. 主题与导航
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '博客', link: '/posts/' },
      { text: '关于', link: '/about/' }
    ],
    sidebar: {
      '/posts/': [
        { text: '博客', items: [{ text: '第一篇博客', link: '/posts/first-post' }] }
      ]
    },
    logo: '/logo.png',
    footer: {
      message: '© 2025 技术博客',
      copyright: 'Powered by VitePress'
    }
  },

  // 3. 构建钩子：生成 .nojekyll（防止 GitHub Pages 过滤文件）
  buildEnd: async () => {
    const dist = './docs/.vitepress/dist'
    if (fs.existsSync(dist)) {
      fs.writeFileSync(`${dist}/.nojekyll`, '')
      console.log('✅ .nojekyll 已生成')
    }
  },

  // 4. SEO 优化（可选）
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }],
    ['meta', { name: 'keywords', content: 'VitePress, 技术博客, 静态站点' }]
  ]
})

🔍 关键说明：

• base: '/'：部署到 username.github.io 时必须为根路径
• .nojekyll：避免 GitHub Pages 误删 _ 开头的文件（如 _assets/）

---

✍️ 五、编写内容

1. 首页（docs/index.md）

---
layout: home
title: 技术博客
hero:
  name: 技术博客
  text: 分享、思考、成长
  tagline: 基于 VitePress 的现代化静态博客
  actions:
    - theme: brand
      text: 查看博客
      link: /posts/
    - theme: alt
      text: 关于我
      link: /about/
features:
  - title: 极速构建
    details: Vite 驱动，毫秒级热更新
  - title: Markdown 增强
    details: 支持 Vue 组件、数学公式、图表
  - title: 免费托管
    details: GitHub Pages + 自动 HTTPS
---

2. 博客文章（docs/posts/first-post.md）

---
title: 我的第一篇 VitePress 博客
date: 2025-10-06
---

# 开始使用 VitePress

这是我的第一篇博客...

3. 关于页（docs/about/index.md）

# 关于我

热爱技术，持续学习。

4. 添加静态资源

将 logo.png、favicon.ico 放入：

docs/.vitepress/public/

VitePress 会自动复制到构建输出根目录。

---

🌐 六、配置自定义域名（关键！）

1. 添加 CNAME 文件

创建：

docs/.vitepress/public/CNAME

内容为你的域名（例如）：

example.com

✅ 此文件将随每次构建自动部署，确保 GitHub Pages 持续识别域名。

2. 配置 DNS（在域名服务商处操作）

添加 A 记录（根域名必须用 A 记录）：

类型	主机	记录值
A	@	185.199.108.153
A	@	185.199.109.153
A	@	185.199.110.153
A	@	185.199.111.153

来源：GitHub 官方文档

---

🤖 七、配置 GitHub Actions 自动部署

1. 创建 Personal Access Token（PAT）

1. 进入 GitHub Tokens 设置页
2. 生成 Classic Token，勾选 ✅ public_repo
3. 复制 token（形如 ghp_xxx...）

2. 添加 Secret

在 源码仓库 my-blog-source 中：

• Settings → Secrets → Actions → New secret
  • Name: DEPLOY_TOKEN
  • Value: 粘贴 PAT

3. 创建工作流文件

创建 .github/workflows/deploy.yml：

name: Deploy VitePress Blog

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install and Build
        run: |
          npm install
          npm run docs:build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.DEPLOY_TOKEN }}
          publish_dir: docs/.vitepress/dist
          external_repository: username/username.github.io
          publish_branch: main

🔁 将 username 替换为你的 GitHub 用户名。

---

🚀 八、首次部署与验证

1. 提交代码

git add .
git commit -m "feat: complete blog setup with CNAME"
git push origin main

2. 验证结果

• 访问 https://username.github.io → 应显示博客
• 访问 https://example.com → 应显示相同内容（DNS 生效后）
• 检查是否启用 HTTPS（地址栏有锁图标）

💡 可用 dnschecker.org 查询全球 DNS 解析状态。

---

🛠️ 九、常见问题排查

问题	原因	解决方案
自定义域名无法访问	DNS 未配置或未生效	检查 A 记录，等待 10 分钟~1 小时
页面空白或 404	base 配置错误	确保 base: '/'
资源 404（CSS/JS）	缺少 .nojekyll	确认 buildEnd 钩子已执行
GitHub Action 失败	publish_dir 路径错误	确保为 docs/.vitepress/dist
HTTPS 未生效	证书未签发	在 username.github.io 的 Settings → Pages 中勾选 Enforce HTTPS

---

🌟 十、后续优化建议

• 迁移旧文章：直接复制 Markdown 到 docs/posts/
• 自定义主题：通过 docs/.vitepress/theme/ 覆盖默认样式
• 添加统计：在 head 中嵌入 Google Analytics 或 百度统计
• 启用搜索：配置 VitePress 内置搜索

---

✅ 总结

通过本文，你已完成：

• ✅ 从零搭建 VitePress 博客项目
• ✅ 配置专业首页与内容结构
• ✅ 实现源码私有 + 自动部署
• ✅ 绑定自定义域名并启用 HTTPS
• ✅ 掌握常见问题排查方法

现在，只需在 my-blog-source 中编写 Markdown，推送代码，你的博客就会自动更新！

🎉 Happy blogging with VitePress!

---

📚 参考资料

• VitePress 官方文档
• GitHub Pages 自定义域名指南
• peaceiris/actions-gh-pages