耽误你一点时间！这份Vuepress搭建博客的保姆级教程请收好！
# 前言
哈喽，大家好，又和大家见面了。这是一期关于用 Vuepress 搭建博客并将它部署到 Github Pages 上的教程文章，事情的起因还得从我上周发的一篇沸点说起。
因此，不负广大掘友众望，这篇教程如约而至。
我的博客地址如下：https://xusssyyy.github.io/blog/
第一次打开的时候可能会比较卡，如果卡的话建议用切换数据流量来打开博客。手机移动端和电脑 PC 端都是可以查看的。
这里我会介绍两版教程，一是基础版，二是升级版。
# 何为 Vuepress
在开始搭建博客前，我们先来介绍一下 Vuepress，这里我用我之前的一篇文章来简单概述一下吧。Vuepress 是由 Vue 支持的静态网站生成工具，Vue 大家都知道或者使用过吧，一种轻量级且好用的框架，因为 Vue 上手起来很简单，所以 Vuepress 使用起来也不难。如果想快速搭建一个静态的博客网站来简单记录记录笔记或者文章，用 Vuepress 是个不错的选择，因为它对新手很友好。
# 基础版
介绍完 Vuepress，我们就可以开始进行博客的搭建了。先给大家看一下最终完成之后的博客项目的目录结构吧。
结构简单清晰明了，没有特别复杂的东西。接下来我开始手把手教大家搭建此项目。
# 本地初步搭建
我们首先创建并进入一个新文件夹，这里我们把它命名为 blogs（博客）吧。
mkdir blogs
cd blogs
然后使用 npm 或者 yarn 进行初始化，我这里使用的是 npm 包管理器。
npm init -y
然后安装 VuePress 为本地依赖。
npm install -D vuepress
完成这些之后开始创建我们的第一篇文档，先创建 docs 文件夹，然后在文件夹下创建 README.md 文件，README.md 文件中我们可以随意加入点内容，比如 Hello Vuepress。
这里需要注意，如果使用如下命令创建的话，后续可能会出现乱码的情况，这时候只需将README.md 的编码格式改为 UTF-8 即可
mkdir docs
echo '# Hello VuePress' > docs/README.md
| 正常的格式 | 会导致乱码的格式 |
|---|---|
最后，我们再向 package.json 中的 scripts 里添加如下代码。
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
完成这些之后一个初步的博客框架就出来了，通过如下代码在本地启动服务器可以查看。
npm run docs:dev
项目运行在 8080 端口。
# 基本配置
一个初步的框架是远远不够将博客支撑起来的，我们还需要做一些基本配置。
# 1. 添加标题和描述
在 docs 文件夹下添加 .vuepress 目录，所有 VuePress 相关的文件都会被放在这里。在 .vuepress 文件夹下添加 config.js，配置网站的标题和描述，此时项目的目录结构是这样的：
docs/
README.md/
.vuepress/
config.js/
config.js 文件的内容如下(标题和描述自定义)：
module.exports = {
title: 'XXX的博客',
description: 'YYY'
}
# 2. 添加导航栏
我们在首页的右上角添加导航栏，需要修改 config.js：
module.exports = {
title: 'XXX的博客',
description: 'YYY',
themeConfig: {
nav: [
{ text: "首页", link: "/" },
{
text: "Shark Xu 的博客",
items: [
{ text: "掘金", link: "https://juejin.cn/user/233526039432445" },
{ text: "Github", link: "https://github.com/Xusssyyy" }
]
}
]
}
}
# 3. 添加侧边栏
现在我们添加一些侧边栏，内容自定义添加，此时项目的目录结构如下：
docs/
README.md/
.vuepress/
config.js/
blogs/
1.md/
2.md/
我们在 config.js 添加如下配置：
module.exports = {
title: 'XXX的博客',
description: 'YYY',
themeConfig: {
nav: [...],
sidebar: [
{
title: "欢迎学习",
path: "/",
collapsable: false, // 是否折叠
children: [{ title: "博客简介", path: "/" }],
},
{
title: "基础篇",
path: "/blogs/1",
collapsable: true,
children: [
{ title: "第一篇", path: "/blogs/1" },
{ title: "第二篇", path: "/blogs/2" },
]
}
]
}
}
此时界面效果如下：
# 加入主题
现在博客的基本功能已经实现，如果还想要更多类似于加载、切换等效果或者功能的话，我们可以直接使用主题，这里我使用的主题是 vuepress-theme-reco (opens new window)，一款简洁而大气的主题。
# 1. vuepress-theme-reco
现在我们安装 vuepress-theme-reco：
npm install vuepress-theme-reco --save-dev
然后需要在 config.js 中引用该主题：
module.exports = {
title: 'XXX的博客',
description: 'YYY',
theme: 'reco',
nav: [...],
themeConfig: [...],
}
此时界面效果如下：
# 2. 其他主题
除了 vuepress-theme-reco 这个主题，还有很多其他主题，比如 vuepress-theme-hope (opens new window) 也会是个不错的主题选择，这里我就不介绍它了，感兴趣的朋友可以去官网上查找它的相关资料。
# 整体样式修改
我们可以通过添加相关文件来修改博客的默认样式。
# 1. 主题色修改
VuePress 默认主题颜色是绿色，我们可以将主题颜色修改为自己喜欢的颜色。在 .vuepress 目录下创建 styles 文件夹，styles 文件夹里创建一个 palette.styl 文件，文件代码如下：
$accentColor = #3178c6 // 蓝色主题色
这就可以将主题颜色改为蓝色了。
# 2. 其他样式修改
如果我们切换到暗黑模式下，可能会发现文字看不清楚，所以我们需要修改文字的颜色和背景色。
在之前创建好的 styles 文件夹下再新建一个 index.styl 文件，文件代码如下：
.dark .content__default code {
background-color: rgba(58,58,92,0.7);
color: #fff;
}
这样就可以解决上面那个问题了。完成这些之后，此时项目的目录结构如下：
最终一个基础版的简单博客界面就搭建好了。
正常模式
暗黑模式
如果后面还需要增加新内容，可以按照上面同样的方式在 blogs 目录下新增 md 文档即可。
# 升级版
之所以称为基础版，是因为我们并没有添加额外的插件来丰富博客。如果想要美化升级自己的博客，接下来我将介绍通过插件来丰富后的升级版博客。
# 分类和标签
我们将重新改变整体的布局，使用另一套布局方式。将上述介绍的侧边栏 slidebar 去除，加入博客配置 blogConfig。
module.exports = {
title: 'XXX的博客',
description: 'YYY',
themeConfig: {
nav: [...],
// 博客配置
blogConfig: {
category: {
location: 2, // 在导航栏菜单中所占的位置，默认2
text: "博客", // 默认文案 “分类”
},
tag: {
location: 4, // 在导航栏菜单中所占的位置，默认4
text: "Tag", // 默认文案 “标签”
},
},
}
}
这时候如果将项目运行起来，博客分类这一栏是不会显示的，因为我们并没有写入分类的内容，而分类内容的写入将在下面的文章信息里介绍。
# 文章信息
文章信息包括很多，比如标题，日期，分类，标签等等，实现这些我们只需要在每篇 md 文档的前面加入如下示例代码即可。
---
title: 手把手教你轻松手写防抖和节流🔥
date: 2023-1-1
categories:
- 前端
tags:
- JavaScript
- 手写
sticky: 1
---
title 是标题，date 是日期，categories 是分类，tags 是标签，可以有多个分类和标签，sticky 可以让文章置顶，数字表示顺序，1 表示在最上面，2 其次。这里的代码格式一定是按照如上写法：变量后面要加冒号，冒号后面要有空格，不要加逗号。
这里的作者名 Shark Xu 是在 config.js 中的 themeConfig 里设置的，这样每篇文章里就会附上设置好的作者名。
author: "Shark Xu",
当我们填写了分类后，就会在博客那一栏下面生成相应的分类，自己需要哪些分类，在里面自定义即可。比如我这里就定义了随笔、前端以及刷题三个分类。
# 日期的格式
对于日期的格式问题，我们只需在 config.js 中加入如下代码即可。这样日期的格式就会从 2023-1-1 变为 2023/1/1。
module.exports = {
...
locales: {
"/": {
lang: "zh-CN",
},
},
...
}
# 头像图标
对于头像图标等这类静态资源，我们需要在 .vuepress 目录下新建 public 文件夹，把它们放在 .vuepress/public 下。这里只需要在 config.js 中的 themeConfig 里加入如下语句：
logo: "/avatar.jpg",
authorAvatar: "/avatar.jpg",
# 首页配置
我们首先在 config.js 中的 themeConfig 里加入如下语句，这是指定的 blog 类型。
type: "blog",
然后在 docs 目录下的 README.md 文档里加入如下代码：
---
home: true
heroImage: "/live.jpg"
heroText: Shark Xu
heroImageStyle:
{
maxHeight: "288px",
display: block,
borderRadius: "19% 81% 23% 77% / 44% 57% 43% 56%",
boxShadow: "0 15px 18px rgba(0,0,0,0.2)",
}
---
像 live.png 这种静态图片资源也是放在 .vuepress/public 下。如果觉得多余，这里的 heroImage 也可以省略。
我们也可以设置首页的背景图片，如果想改变背景图片的样式，可以通过 bgImageStyle 来实现想要的效果。
---
home: true
heroText: Shark Xu
bgImage: "/blue.jpg"
bgImageStyle: { height: "100%", boxShadow: "0 15px 18px rgba(0,0,0,0.2)" }
---
# 添加插件
这里就到了大家最感兴趣的插件部分了。我的博客里总共安装了三个插件，分别是樱花效果，鼠标点击效果以及左下角的音乐播放器。
樱花效果
首先先安装它：
npm install vuepress-plugin-sakura -D
然后在 config.js 中加入 plugins：
module.exports = {
...
plugins: [
[
"sakura",
{
num: 20, // 默认数量
show: true, // 是否显示
zIndex: -1, // 层级
img: {
replace: false, // false 默认图 true 换图 需要填写httpUrl地址
},
},
],
]
...
}
鼠标点击效果
安装：
npm install vuepress-plugin-cursor-effects -D
使用：
plugins: [
[...],
[
"cursor-effects",
{
size: 4, // size of the particle, default: 2
shape: "star", // ['star' | 'circle'], // shape of the particle, default: 'star'
zIndex: 999999999, // z-index property of the canvas, default: 999999999
},
],
]
音乐播放器
安装：
npm install @vuepress-reco/vuepress-plugin-bgm-player -D
使用：
plugins: [
[...],
[...],
[
"@vuepress-reco/vuepress-plugin-bgm-player",
{
audios: [
{
name: "강남역 4번 출구",
artist: "Plastic / Fallin` Dild",
url: "https://assets.smallsunnyfox.com/music/2.mp3",
cover: "https://assets.smallsunnyfox.com/music/3.jpg",
},
{
name: "팔베개",
artist: "최낙타",
url: "https://assets.smallsunnyfox.com/music/3.mp3",
cover:
"https://p1.music.126.net/qTSIZ27qiFvRoKj-P30BiA==/109951165895951287.jpg?param=200y200",
},
],
// 是否默认缩小
autoShrink: true,
// 缩小时缩为哪种模式
shrinkMode: "float",
// 悬浮窗样式
floatStyle: { bottom: "20px", "z-index": "999999" },
},
],
]
这里需要注意的是，歌曲 url 链接格式需为 MP3 格式，否则无法播放。
如果大家还对其他插件感兴趣，可以在网上直接搜索 Vuepress 插件就可以查找到更多内容。
至此，博客的效果如下所示：
界面效果
动态效果
以上就是关于博客的一些优化以及插件的使用，下面是两种不同版本的对比。
| 基础版 | 升级版 |
|---|---|
# 部署 Github Pages
到这里，我们的博客网站基本搭建好了。这里将介绍如何将静态博客部署到 Github Pages 上。由于我没有服务器，所以我将博客部署到 Github Pages 上了，有服务器的小伙伴可以将它部署到服务器上，这是最好的选择。（后面我争取也弄个服务器来琢磨一下）
我们首先在 Github 上新建一个仓库，名字自定义，这里我依旧取名为 blogs。记得将项目 git 初始化。
然后我们需要在 config.js 添加一个 base 路径配置：
module.exports = {
...
// 和仓库名相同
base: '/blogs/',
...
}
然后我们在项目 docs 目录下创建一个脚本文件 deploy.sh，注意修改一下对应的用户名和仓库名，相关代码如下：
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run docs:build
# 进入生成的文件夹
cd docs/.vuepress/dist
git init
git add -A
git commit -m 'deploy'
# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:Xusssyyy/blogs.git master:gh-pages 我自己的格式
git push -f git@github.com:XXX/XXX.git master:gh-pages
cd -
新建一个终端，执行 sh deploy.sh
sh deploy.sh
执行这行命令要选择 Git Bash。
项目就会开始构建，然后上传到远程仓库上。
最终我们可以在仓库的 Settings -> Pages 中看到最后的地址。
我最后生成的地址：https://xusssyyy.github.io/blog/
至此，我们完成了相关部署，通过链接就可查看博客。如果要更新博客内容的话，将代码更新提交之后，执行脚本文件 deploy.sh 就可完成更新内容。
# 总结
以上就是使用 VuePress 搭建个人博客的大致流程，并使用 Github Pages 进行了简单部署。关于我在搭建过程中遇到的问题以及踩到的坑基本都在文章里说明了，如果大家在搭建的过程中遇到了问题，我们可以在评论区交流讨论，发现问题，及时解决问题。整个博客跟着文章搭建一遍的话很快就可以完成，所以建议大家手动敲一遍。
关于于博客的更多美化和升级，大家也可以去 Vuepress 的官方文档查找更多详细资料，我这里介绍了我的博客的一些升级步骤。
如果大家觉得这篇文章对你有帮助，不要忘了给我一个小小的赞 ღ( ´･ᴗ･` ) 。
