个人博客搭建指南
从零开始,打造属于你自己的技术博客
文档版本: 1.0 最后更新: 2025-11-17 适用人群: 想要搭建个人博客的开发者和技术爱好者 技术栈: VuePress 2.0 + GitHub Pages
目录
为什么要搭建个人博客
对个人成长的价值
知识沉淀
- 系统化整理所学知识
- 加深对技术的理解
- 建立个人知识库
- 方便日后查阅复习
技能提升
- 提高技术写作能力
- 锻炼表达和总结能力
- 学习前端开发技术
- 掌握运维部署技能
职业发展
- 展示技术实力
- 建立个人品牌
- 增加面试竞争力
- 结识同行朋友
为什么选择自建而不是平台
优势对比:
| 特性 | 自建博客 | 第三方平台 |
|---|---|---|
| 自由度 | ✅ 完全自由 | ❌ 受平台限制 |
| 个性化 | ✅ 高度定制 | ❌ 模板固定 |
| 数据所有权 | ✅ 完全拥有 | ❌ 平台控制 |
| 技术学习 | ✅ 学到很多 | ❌ 学习较少 |
| 成本 | ✅ 免费(GitHub Pages) | ✅/❌ 部分免费 |
| 上手难度 | ⚠️ 需要学习 | ✅ 简单快速 |
结论: 如果你是技术人员,想要更高的自由度和学习机会,自建博客是更好的选择。
技术选型对比
主流静态站点生成器
1. VuePress (本教程选择)
优点:
- 🎯 专为技术文档设计
- 📝 Markdown 支持完善
- 🚀 Vue 3 驱动,性能优秀
- 🎨 主题系统完善
- 🔌 插件生态丰富
- 📱 移动端友好
缺点:
- 中文文档相对较少
- 需要一定 Vue 基础(非必需)
适合人群:
- 技术博客作者
- 前端开发者
- Vue 爱好者
2. Hexo
优点:
- 📚 中文文档丰富
- 🎨 主题数量多
- 🔧 配置简单
- 👥 社区活跃
缺点:
- 基于 EJS,不够现代
- 构建速度较慢
- 主题质量参差不齐
适合人群:
- 博客新手
- 追求简单的用户
3. Hugo
优点:
- ⚡ 构建速度极快
- 🎯 功能强大
- 🌍 国际化支持好
缺点:
- Go 语言,不够亲和
- 中文资源较少
- 学习曲线陡峭
适合人群:
- 大型博客站点
- 追求极致性能
4. Docusaurus
优点:
- 📖 文档站点专业
- ⚛️ React 生态
- 🎨 Facebook 出品
缺点:
- 偏向文档而非博客
- 配置相对复杂
适合人群:
- React 开发者
- 开源项目文档
本教程选择 VuePress 的理由
- 技术先进: Vue 3 + Vite,开发体验好
- 文档友好: 专为技术写作设计
- 易于定制: 可以轻松添加 Vue 组件
- 性能优秀: 构建快速,加载迅速
- 生态完善: 插件和主题丰富
环境准备
必需软件安装
1. Node.js
推荐版本: 18.x 或更高
安装方法:
Windows:
- 访问 Node.js 官网
- 下载 LTS 版本
- 运行安装程序
- 验证安装:
node -v
# 输出: v18.x.x 或更高
npm -v
# 输出: 9.x.x 或更高
macOS:
# 使用 Homebrew
brew install node@18
# 验证
node -v
npm -v
Linux (Ubuntu/Debian):
# 使用 NodeSource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# 验证
node -v
npm -v
2. Git
安装方法:
Windows:
- 访问 Git 官网
- 下载安装程序
- 安装时选择默认选项
- 验证:
git --version
macOS:
brew install git
git --version
Linux:
sudo apt-get install git
git --version
配置 Git:
git config --global user.name "你的名字"
git config --global user.email "your_email@example.com"
3. 代码编辑器
推荐 Visual Studio Code:
- 访问 VS Code 官网
- 下载并安装
- 安装推荐插件:
- Vetur 或 Volar - Vue 支持
- Markdown All in One - Markdown 增强
- GitLens - Git 可视化
- Chinese Language Pack - 中文界面
账号注册
GitHub 账号
- 访问 GitHub
- 点击 Sign up 注册
- 验证邮箱
- 完善个人资料
为什么需要 GitHub:
- 托管博客源代码
- 使用 GitHub Pages 免费部署
- 版本控制和备份
快速开始
如果你想直接使用本项目作为模板快速搭建,可以按以下步骤:
方式一:克隆本项目
# 1. 克隆项目
git clone https://github.com/zephyrnan/zephyrnan.github.io.git my-blog
cd my-blog
# 2. 删除原有 Git 历史
rm -rf .git
git init
# 3. 安装依赖
npm install
# 4. 启动开发服务器
npm run dev
# 5. 浏览器访问 http://localhost:8080
方式二:使用模板创建
- 访问 本项目 GitHub 仓库
- 点击 "Use this template" 按钮
- 填写仓库信息:
- Repository name:
你的用户名.github.io - Description: 个人博客
- Public: 选择 Public
- Repository name:
- 克隆到本地:
git clone https://github.com/你的用户名/你的用户名.github.io.git
cd 你的用户名.github.io
npm install
npm run dev
个性化配置
修改基本信息:
编辑 docs/.vuepress/config.js:
export default defineUserConfig({
lang: 'zh-CN',
title: '你的博客名称', // 修改这里
description: '你的博客描述', // 修改这里
base: '/',
})
更换图片:
docs/.vuepress/public/author.jpg- 替换为你的头像docs/.vuepress/public/bg.jpg- 替换为你的网站图标
修改关于页面:
编辑 docs/about.md:
# 关于我
你的个人简介...
## 技能栈
- 你的技能1
- 你的技能2
## 联系方式
- GitHub: [你的GitHub](https://github.com/你的用户名)
- Email: your_email@example.com
从零搭建详细步骤
如果你想完全从零开始学习,跟着这个步骤来。
第一步:创建项目
# 1. 创建项目目录
mkdir my-blog
cd my-blog
# 2. 初始化 npm 项目
npm init -y
# 3. 安装 VuePress
npm install -D vuepress@next @vuepress/bundler-vite@next @vuepress/theme-default@next
# 4. 安装 Vue 3
npm install -D vue@next
第二步:创建目录结构
# 创建文档目录
mkdir -p docs/.vuepress/public
mkdir -p docs/.vuepress/components
mkdir -p docs/posts
目录结构:
my-blog/
├── docs/
│ ├── .vuepress/
│ │ ├── components/ # Vue 组件
│ │ ├── public/ # 静态资源
│ │ ├── config.js # 配置文件
│ │ └── client.js # 客户端配置
│ ├── posts/ # 博客文章
│ ├── README.md # 首页
│ └── about.md # 关于页面
├── package.json
└── .gitignore
第三步:配置 package.json
编辑 package.json,添加脚本:
{
"name": "my-blog",
"version": "1.0.0",
"description": "我的个人博客",
"scripts": {
"dev": "vuepress dev docs",
"build": "vuepress build docs",
"clean": "rm -rf docs/.vuepress/.cache docs/.vuepress/.temp docs/.vuepress/dist"
},
"keywords": ["blog", "vuepress"],
"author": "你的名字",
"license": "MIT"
}
第四步:创建配置文件
创建 docs/.vuepress/config.js:
// 导入VuePress核心模块
import { viteBundler } from '@vuepress/bundler-vite' // Vite打包工具,比Webpack更快
import { defaultTheme } from '@vuepress/theme-default' // 默认主题
import { defineUserConfig } from 'vuepress' // 配置定义函数
export default defineUserConfig({
// 语言设置
lang: 'zh-CN', // 设置网站语言为中文,影响默认文本和日期格式
// 网站标题(显示在浏览器标签和页面header)
title: '我的技术博客', // 会显示在每个页面的标题栏
// 网站描述(用于SEO,显示在搜索结果)
description: '记录学习与成长', // 会被搜索引擎索引
// 部署基础路径
base: '/', // GitHub用户站点用'/',项目站点用'/仓库名/'
// 网站图标
head: [
['link', { rel: 'icon', href: '/favicon.ico' }], // favicon路径相对于public目录
],
// 打包工具配置
bundler: viteBundler(), // 使用Vite进行快速构建,支持HMR热更新
// 主题配置
theme: defaultTheme({
// Logo(显示在导航栏左侧)
logo: '/logo.png', // 路径相对于public目录
// 导航栏配置
navbar: [
{ text: '首页', link: '/' }, // text:显示文字, link:跳转路径
{ text: '文章', link: '/posts/' }, // 以/结尾表示目录首页
{ text: '关于', link: '/about.md' }, // 可以直接链接到md文件
],
// 侧边栏配置(支持多级菜单)
sidebar: {
'/posts/': [ // 指定/posts/路径下的侧边栏
{
text: '文章列表', // 分组标题
children: [ // 子菜单项
'/posts/my-first-post.md', // 文章路径
],
},
],
},
// 仓库配置(显示在导航栏右侧)
repo: 'https://github.com/你的用户名/你的仓库', // GitHub仓库地址
// 编辑链接(显示"编辑此页"按钮)
editLink: false, // 关闭编辑链接功能
// 最后更新时间(自动从Git获取)
lastUpdated: true, // 开启显示最后更新时间
lastUpdatedText: '最后更新', // 自定义显示文本
// 贡献者列表(从Git历史获取)
contributors: false, // 关闭贡献者显示
}),
})
⚠️ 注意事项:
- base路径配置: GitHub用户站点(
username.github.io)使用base: '/',项目站点(username.github.io/repo)使用base: '/repo/',配置错误会导致资源404- public目录: 所有静态资源(图片、favicon等)必须放在
docs/.vuepress/public/目录,引用时路径从根目录开始- 导航栏链接: 链接以
/开头表示从根目录开始,以.md结尾会自动转换为HTML路径- 侧边栏配置: 可以按路径分组配置不同侧边栏,支持嵌套children
- Git集成:
lastUpdated和contributors需要在Git仓库中才能正常工作,本地非Git环境不显示- 构建时间: Vite打包比Webpack快3-5倍,大型项目推荐使用
// 常见错误:base配置错误 // 项目站点错误配置 base: '/', // ❌ 项目站点不能用根路径 // 正确配置 base: '/my-blog/', // ✅ 项目站点必须加仓库名 // 常见错误:静态资源路径错误 logo: './public/logo.png', // ❌ 不要包含public logo: '/logo.png', // ✅ 直接从根路径开始 // 常见错误:侧边栏路径不一致 sidebar: { '/posts': [...], // ❌ 缺少结尾斜杠 '/posts/': [...], // ✅ 路径要以/结尾 }🎯 实际应用场景:
// 场景1:多语言配置 export default defineUserConfig({ locales: { '/': { lang: 'zh-CN', title: '我的博客', }, '/en/': { lang: 'en-US', title: 'My Blog', } }, theme: defaultTheme({ locales: { '/': { navbar: [...] }, '/en/': { navbar: [...] } } }) }) // 场景2:多级导航菜单 navbar: [ { text: '技术分类', children: [ { text: '前端', link: '/frontend/' }, { text: '后端', link: '/backend/' }, { text: '数据库', link: '/database/' } ] } ] // 场景3:动态侧边栏(自动从目录生成) import { getDirname, path } from '@vuepress/utils' import fs from 'fs' const __dirname = getDirname(import.meta.url) const postsPath = path.resolve(__dirname, '../../posts') const postFiles = fs.readdirSync(postsPath).filter(f => f.endsWith('.md')) sidebar: { '/posts/': [ { text: '全部文章', children: postFiles.map(f => `/posts/${f}`) } ] } // 场景4:添加自定义head标签(SEO优化) head: [ ['link', { rel: 'icon', href: '/favicon.ico' }], ['meta', { name: 'keywords', content: 'Vue,JavaScript,前端' }], ['meta', { name: 'author', content: '你的名字' }], ['meta', { property: 'og:title', content: '我的博客' }], ['meta', { property: 'og:image', content: '/og-image.jpg' }], // 百度统计 ['script', {}, ` var _hmt = _hmt || []; (function() { var hm = document.createElement("script"); hm.src = "https://hm.baidu.com/hm.js?你的ID"; var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(hm, s); })(); `] ] // 场景5:自定义404页面和首页布局 export default defineUserConfig({ theme: defaultTheme({ notFound: ['页面不存在', '找不到该页面'], backToHome: '返回首页', home: '/', // 自定义容器样式 tip: '提示', warning: '警告', danger: '危险' }) })
第五步:创建首页
创建 docs/README.md:
---
home: true
heroText: 欢迎来到我的博客
tagline: 记录技术,分享成长
actions:
- text: 开始阅读
link: /posts/
type: primary
- text: 关于我
link: /about.md
type: secondary
features:
- title: 📝 技术笔记
details: 记录学习过程中的技术知识点
- title: 💡 实践经验
details: 分享项目开发中的实战经验
- title: 🔧 工具分享
details: 推荐好用的开发工具和资源
footer: MIT Licensed | Copyright © 2025-present
---
## 最新文章
- [我的第一篇博客](/posts/my-first-post.md)
## 关于本站
这是一个基于 VuePress 2.0 搭建的个人技术博客。
第六步:创建文章
创建 docs/posts/README.md:
# 文章列表
## 全部文章
- [我的第一篇博客](/posts/my-first-post.md)
创建 docs/posts/my-first-post.md:
---
title: 我的第一篇博客
date: 2025-11-17
categories:
- 随笔
tags:
- 开始
---
# 我的第一篇博客
> 记录搭建博客的过程
## 为什么搭建博客
这里写你搭建博客的原因...
## 搭建过程
这里记录你的搭建过程...
## 总结
这里写你的总结...
第七步:创建关于页面
创建 docs/about.md:
# 关于我
## 个人简介
你好,我是 XXX...
## 技能栈
- **前端**: HTML, CSS, JavaScript
- **框架**: Vue, React
- **后端**: Node.js
- **数据库**: MySQL
## 联系方式
- GitHub: [你的用户名](https://github.com/你的用户名)
- Email: your_email@example.com
- 微信: your_wechat
## 关于本站
本站使用 VuePress 2.0 搭建,托管在 GitHub Pages。
技术栈:
- VuePress 2.0
- Vue 3
- Vite
- GitHub Pages
第八步:配置 .gitignore
创建 .gitignore:
# Node
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# 注意：package-lock.json 应该提交到仓库，不要忽略
# 否则 GitHub Actions 里的 npm ci 会因为找不到 lock 文件而失败
# VuePress
docs/.vuepress/.cache/
docs/.vuepress/.temp/
docs/.vuepress/dist/
# IDE
.idea/
.vscode/
*.suo
*.ntvs*
*.njsproj
*.sln
# OS
.DS_Store
Thumbs.db
第九步:测试运行
# 启动开发服务器
npm run dev
访问 http://localhost:8080,查看效果。
如果一切正常,你应该能看到博客首页!
内容创作指南
Markdown 基础
标题
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
文本样式
**粗体文本**
*斜体文本*
~~删除线~~
`行内代码`
列表
无序列表:
- 项目 1
- 项目 2
- 子项目 2.1
- 子项目 2.2
有序列表:
1. 第一项
2. 第二项
3. 第三项
链接和图片
[链接文本](https://example.com)
引用
> 这是一段引用文本
> 可以有多行
代码块
```javascript
function hello() {
console.log('Hello World')
}
```
表格
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |
VuePress 扩展语法
自动目录
[[toc]]
提示容器
::: tip 提示
这是一个提示
:::
::: warning 警告
这是一个警告
:::
::: danger 危险
这是危险警告
:::
::: details 点击查看详情
隐藏的详细内容
:::
代码高亮
```javascript{1,3-5}
console.log('第1行高亮')
console.log('不高亮')
console.log('第3-5行高亮')
console.log('高亮')
console.log('高亮')
```
文章模板
推荐的文章结构:
---
title: 文章标题
date: 2025-11-17
categories:
- 分类名称
tags:
- 标签1
- 标签2
---
# 文章标题
> 文章简介或引言
## 目录
[[toc]]
## 引言
为什么写这篇文章...
## 正文部分一
### 小节标题
内容...
#### 更小的标题
细节内容...
## 正文部分二
### 示例代码
```javascript
// 代码示例
const example = 'Hello World'
```
### 图片说明
## 总结
文章总结...
## 参考资料
- [参考链接1](https://example.com)
- [参考链接2](https://example.com)
写作建议
内容质量:
- ✅ 标题简洁明了
- ✅ 结构清晰有逻辑
- ✅ 代码示例完整可运行
- ✅ 配图清晰有说明
- ✅ 总结提炼要点
写作技巧:
- 使用简单直白的语言
- 多用例子和图示
- 代码要有注释
- 避免长篇大论
- 定期更新修正
SEO 优化:
- 标题包含关键词
- 合理使用标题层级
- 添加 meta 描述
- 内链外链结合
功能扩展
添加评论系统
方案选择
Valine (推荐):
- ✅ 无需登录
- ✅ Markdown 支持
- ✅ 访问量统计
- ❌ 需要 LeanCloud
Giscus:
- ✅ 基于 GitHub Discussions
- ✅ 无需额外服务
- ❌ 需要 GitHub 账号
Gitalk:
- ✅ 基于 GitHub Issues
- ❌ 需要 GitHub OAuth
集成 Valine 评论
1. 注册 LeanCloud
- 访问 LeanCloud
- 注册并登录
- 创建应用(开发版免费)
- 获取 AppID 和 AppKey
2. 安装 Valine
npm install valine
3. 创建评论组件
创建 docs/.vuepress/components/ValineComment.vue:
<template>
<!-- 评论容器,Valine会在此挂载 -->
<div id="vcomments"></div>
</template>
<script>
export default {
name: 'ValineComment', // 组件名称,用于在Markdown中引用
mounted() {
// 组件挂载后初始化评论系统
this.initValine() // 页面加载完成后才执行,确保DOM已渲染
},
methods: {
async initValine() {
// 动态导入 Valine (按需加载,减小初始包体积)
const Valine = (await import('valine')).default // 使用ES6 dynamic import
// 创建Valine实例并配置
new Valine({
el: '#vcomments', // 挂载到的DOM元素选择器
appId: '你的AppID', // LeanCloud应用ID(在LeanCloud控制台获取)
appKey: '你的AppKey', // LeanCloud应用Key(在LeanCloud控制台获取)
placeholder: '说点什么吧...', // 评论框占位文字
avatar: 'monsterid', // 头像风格(可选:identicon/wavatar/robohash等)
visitor: true, // 开启文章访问量统计
highlight: true, // 代码高亮(评论中的代码块)
recordIP: false, // 不记录评论者IP地址(保护隐私)
})
// 注意:初始化后Valine会自动加载该页面的所有评论
}
}
}
</script>
⚠️ 注意事项:
- LeanCloud配置: 必须先在LeanCloud注册账号并创建应用,否则评论系统无法工作
- 安全域名: 必须在LeanCloud控制台设置→安全中心→Web安全域名中添加
https://你的域名和localhost:8080,否则会报CORS错误- 动态导入: 使用
import('valine')而不是import Valine from 'valine',避免首屏加载过大- 挂载时机: 必须在
mounted()钩子中初始化,在created()中会因DOM未渲染而报错- 唯一ID: Valine根据页面URL自动区分不同文章的评论,确保每篇文章URL唯一
- 数据存储: 评论数据存储在LeanCloud的
Comment表中,可以在控制台查看和管理- 实名制: 如需实名评论,需要配置
requiredFields: ['nick', 'mail']// 常见错误:在created钩子中初始化 created() { this.initValine() // ❌ 此时DOM未渲染,#vcomments不存在 } mounted() { this.initValine() // ✅ DOM已渲染,可以挂载 } // 常见错误:同步导入Valine import Valine from 'valine' // ❌ 会增加首屏包体积 const Valine = (await import('valine')).default // ✅ 按需加载 // 常见错误:未配置安全域名 // 浏览器控制台会显示: // Access to XMLHttpRequest has been blocked by CORS policy // 解决:在LeanCloud控制台添加域名白名单🎯 实际应用场景:
<!-- 场景1:多语言评论系统 --> <script> export default { methods: { async initValine() { const Valine = (await import('valine')).default const lang = this.$page.lang === 'en-US' ? 'en' : 'zh-CN' new Valine({ el: '#vcomments', appId: '你的AppID', appKey: '你的AppKey', lang: lang, // 动态设置语言 placeholder: lang === 'zh-CN' ? '说点什么...' : 'Leave a comment...' }) } } } </script> <!-- 场景2:实名评论+邮件通知 --> <script> export default { methods: { async initValine() { const Valine = (await import('valine')).default new Valine({ el: '#vcomments', appId: '你的AppID', appKey: '你的AppKey', requiredFields: ['nick', 'mail'], // 必填昵称和邮箱 notify: true, // 开启邮件通知(需配置LeanCloud邮件服务) verify: true, // 开启验证码(防止垃圾评论) pageSize: 10, // 每页显示10条评论 avatar: 'wavatar', // 更换头像风格 }) } } } </script> <!-- 场景3:深色主题适配 --> <template> <div id="vcomments" :class="isDark ? 'valine-dark' : ''"></div> </template> <script> export default { computed: { isDark() { return this.$store.state.theme === 'dark' // 根据主题状态切换 } }, methods: { async initValine() { const Valine = (await import('valine')).default new Valine({ el: '#vcomments', appId: '你的AppID', appKey: '你的AppKey' }) } } } </script> <style scoped> .valine-dark { color-scheme: dark; /* 深色模式样式 */ } </style> <!-- 场景4:带表情包的评论 --> <script> export default { methods: { async initValine() { const Valine = (await import('valine')).default new Valine({ el: '#vcomments', appId: '你的AppID', appKey: '你的AppKey', emojiCDN: 'https://cdn.jsdelivr.net/gh/walinejs/emojis@1.0.0/bilibili', emojiMaps: { 'tv_doge': '滑稽', 'tv_ok': 'OK', 'tv_smile': '微笑' } }) } } } </script> <!-- 场景5:评论管理后台 --> <!-- 在LeanCloud控制台可以: --> <!-- 1. 查看所有评论(数据存储→Comment表) --> <!-- 2. 删除垃圾评论 --> <!-- 3. 导出评论数据 --> <!-- 4. 设置敏感词过滤 --> <!-- 5. 查看访问量统计(数据存储→Counter表) -->
4. 在文章中使用
# 文章内容
...
## 评论
<ValineComment />
5. 配置安全域名
在 LeanCloud 控制台:
- 设置 → 安全中心
- Web 安全域名添加:
https://你的用户名.github.iolocalhost:8080
添加搜索功能
npm install -D @vuepress/plugin-search@next
修改 config.js:
import { searchPlugin } from '@vuepress/plugin-search'
export default defineUserConfig({
plugins: [
searchPlugin({
// 搜索框占位符
locales: {
'/': {
placeholder: '搜索',
},
},
// 最大建议数
maxSuggestions: 10,
}),
],
})
添加阅读时间
npm install -D @vuepress/plugin-reading-time@next
import { readingTimePlugin } from '@vuepress/plugin-reading-time'
export default defineUserConfig({
plugins: [
readingTimePlugin(),
],
})
添加代码复制按钮
npm install -D @vuepress/plugin-copy-code@next
import { copyCodePlugin } from '@vuepress/plugin-copy-code'
export default defineUserConfig({
plugins: [
copyCodePlugin({
showInMobile: true,
}),
],
})
添加图片缩放
npm install -D @vuepress/plugin-medium-zoom@next
import { mediumZoomPlugin } from '@vuepress/plugin-medium-zoom'
export default defineUserConfig({
plugins: [
mediumZoomPlugin(),
],
})
添加百度统计
1. 注册百度统计
访问 百度统计
2. 添加网站
创建网站后获取统计代码
3. 配置到博客
修改 config.js:
export default defineUserConfig({
head: [
['script', {}, `
var _hmt = _hmt || [];
(function() {
var hm = document.createElement("script");
hm.src = "https://hm.baidu.com/hm.js?你的统计ID";
var s = document.getElementsByTagName("script")[0];
s.parentNode.insertBefore(hm, s);
})();
`],
],
})
部署上线
GitHub Pages 部署
方法一:使用部署脚本(推荐)
1. 创建部署脚本
创建 deploy.sh:
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run build
# 进入生成的文件夹
cd docs/.vuepress/dist
# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果发布到 https://用户名.github.io
git push -f git@github.com:用户名/用户名.github.io.git main
# 如果发布到 https://用户名.github.io/仓库名
# git push -f git@github.com:用户名/仓库名.git main:gh-pages
cd -
2. 修改权限(macOS/Linux)
chmod +x deploy.sh
3. 执行部署
# Windows Git Bash
bash deploy.sh
# macOS/Linux
./deploy.sh
方法二:GitHub Actions 自动部署
1. 创建工作流文件
创建 .github/workflows/deploy.yml:
name: Deploy to GitHub Pages
on:
push:
branches:
- main # 监听 main 分支
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # lastUpdated 需要完整 Git 历史
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 18
cache: npm # 缓存依赖，加快构建
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/.vuepress/dist
2. 推送代码
git add .
git commit -m "Add GitHub Actions workflow"
git push
3. 配置 GitHub Pages
- 进入仓库 Settings
- 找到 Pages 设置
- Source 选择
gh-pages分支 - 保存
优点:
- 推送后自动部署
- 无需本地构建
- 构建日志清晰
自定义域名
1. 购买域名
推荐域名商:
2. 配置 DNS
添加 CNAME 记录:
类型: CNAME
主机记录: blog 或 @
记录值: 你的用户名.github.io
3. 添加 CNAME 文件
在 docs/.vuepress/public/ 创建 CNAME 文件:
blog.example.com
4. 重新部署
npm run build
# 推送或运行部署脚本
5. 等待生效
通常需要 10 分钟到 24 小时。
Vercel 部署(推荐)
优点:
- 全球 CDN
- 自动部署
- 免费 HTTPS
- 速度更快
步骤:
- 访问 Vercel
- 使用 GitHub 登录
- Import Project
- 选择你的博客仓库
- 配置:
- Build Command:
npm run build - Output Directory:
docs/.vuepress/dist
- Build Command:
- Deploy
SEO 优化
Meta 标签优化
修改 config.js:
export default defineUserConfig({
head: [
// 网站图标
['link', { rel: 'icon', href: '/favicon.ico' }],
// 关键词
['meta', { name: 'keywords', content: 'JavaScript,Vue,前端开发,技术博客' }],
// 作者
['meta', { name: 'author', content: '你的名字' }],
// Open Graph
['meta', { property: 'og:title', content: '你的博客名称' }],
['meta', { property: 'og:description', content: '博客描述' }],
['meta', { property: 'og:type', content: 'website' }],
['meta', { property: 'og:url', content: 'https://你的域名' }],
['meta', { property: 'og:image', content: '/og-image.jpg' }],
// Twitter Card
['meta', { name: 'twitter:card', content: 'summary_large_image' }],
['meta', { name: 'twitter:title', content: '你的博客名称' }],
['meta', { name: 'twitter:description', content: '博客描述' }],
// 主题色
['meta', { name: 'theme-color', content: '#1e88e5' }],
],
})
Sitemap 生成
npm install -D @vuepress/plugin-sitemap@next
import { sitemapPlugin } from '@vuepress/plugin-sitemap'
export default defineUserConfig({
plugins: [
sitemapPlugin({
hostname: 'https://你的域名.com',
}),
],
})
Google Search Console
- 访问 Google Search Console
- 添加网站
- 验证所有权
- 提交 sitemap.xml
持续维护
内容更新
定期更新:
- 每周 1-2 篇新文章
- 更新过时内容
- 修正错误
内容规划:
- 技术学习笔记
- 项目实战经验
- 工具使用教程
- 问题解决方案
性能优化
图片优化:
- 使用 WebP 格式
- 压缩图片大小
- 懒加载图片
代码优化:
- 减少插件数量
- 按需加载组件
- 优化构建配置
备份策略
Git 备份:
# 定期推送到 GitHub
git push origin main
多平台备份:
- GitHub(主)
- Gitee(镜像)
- 本地备份
监控分析
访问统计:
- 百度统计
- Google Analytics
性能监控:
- PageSpeed Insights
- Lighthouse
常见问题
构建问题
Q: 构建失败怎么办?
A: 清理缓存重试:
npm run clean
rm -rf node_modules package-lock.json
npm install
npm run build
Q: 端口被占用?
A: 更换端口:
npm run dev -- --port 8081
部署问题
Q: GitHub Pages 404?
A: 检查 config.js 中的 base 配置:
- 用户站点:
base: '/' - 项目站点:
base: '/仓库名/'
Q: CSS 样式丢失?
A: 检查 base 路径配置是否正确。
功能问题
Q: 评论系统不显示?
A:
- 检查 LeanCloud 安全域名
- 查看浏览器控制台错误
- 确认 AppID 和 AppKey 正确
Q: 搜索不工作?
A: 确认已安装搜索插件并正确配置。
进阶优化
主题定制
自定义颜色:
创建 docs/.vuepress/styles/palette.scss:
// 注意：SCSS 变量用「冒号 + 分号」，不要写成等号（那是 Stylus 语法）
// 主题色（VuePress 2 默认主题的品牌色变量名为 $c-brand）
$c-brand: #1e88e5;
// 文本颜色
$c-text: #2c3e50;
// 边框颜色
$c-border: #eaecef;
// 代码块背景色
$code-bg-color: #282c34;
自定义样式:
创建 docs/.vuepress/styles/index.scss:
// 自定义字体
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}
// 自定义代码块
div[class*="language-"] {
border-radius: 8px;
}
// 响应式调整
@media (max-width: 768px) {
.theme-default-content {
padding: 1rem;
}
}
添加动态效果
粒子背景:
在 client.js 中添加 Canvas 粒子效果(参考本项目源码)。
点击特效:
添加点击 emoji 特效(参考本项目源码)。
返回顶部:
主题自带,或自定义按钮。
PWA 支持
npm install -D @vuepress/plugin-pwa@next
import { pwaPlugin } from '@vuepress/plugin-pwa'
export default defineUserConfig({
plugins: [
pwaPlugin({
skipWaiting: true,
}),
],
})
RSS 订阅
npm install -D @vuepress/plugin-feed@next
import { feedPlugin } from '@vuepress/plugin-feed'
export default defineUserConfig({
plugins: [
feedPlugin({
hostname: 'https://你的域名.com',
}),
],
})
结语
恭喜你!如果你跟着本教程走到这里,你应该已经拥有了一个功能完善的个人博客。
下一步:
- 🎨 个性化你的博客主题
- ✍️ 开始写第一篇文章
- 📢 分享你的博客给朋友
- 💪 持续学习和更新
推荐资源:
本项目:
祝你博客写作愉快!📝
💬 评论交流
有任何问题或建议,欢迎在下方留言交流!
作者: 楠渡余生 GitHub: @zephyrnan最后更新: 2025-11-17 License: MIT
✅ 评论组件已加载