保姆级VuePress + Github Pages搭建博客

一直都是使用CSDN写一些博文，最近突发奇想想试用下免费的Github Pages搭建一下博客，跟上大家的脚步👣，VuePress官网文档写得还算是挺全面的，但是我在进行部署的时候踩了不少坑，记录下来方便大家上手，减少踩坑。

快速搭建VuePress

一个 VuePress 网站是一个由 Vue (opens new window)、Vue Router (opens new window)和 webpack (opens new window)驱动的单页应用

快速上手

1. 创建并进入一个新目录

mkdir blog 
cd blog

2. 使用npm进行初始化

npm init

3. 将VuePress安装为本地依赖（我使用的是v1.x版本）

npm install -D vuepress

4. 新建一个docs新目录，并且创建一个新文档（因为VuePress使用docs作为根目录，所以这个 README.md 相当于主页）

mkdir docs && echo '# Hello VuePress' > docs/README.md

5. 在 package.json 中添加script

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

6. 在docs目录下创建一个 .vuepress 目录，并创建一个新的config.js文件

cd docs
mkdir .vuepress

此时你的目录结构为

├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

7. 在本地启动服务器

npm run docs:dev

此刻VuePress 会在 http://localhost:8080 (opens new window)启动一个热重载的开发服务器。

现在，我们已经实现了一个简单可用的 VuePress 文档。

简单配置

一个 VuePress 网站必要的配置文件是 .vuepress/config.js，所以我们在config.js内配置所需要的信息，以下所有的代码块都是写在config.js文件内，包在module.exports对象中

基础信息

module.exports = {
  title: 'Jessie的个人技术博客',
  description: '办法总比问题多',
}

配置中文

module.exports = {
  title: 'Jessie的个人技术博客',
  description: '办法总比问题多',
  locales: {
    "/": {
        lang: "zh-CN",
    },
  },
}

配置主题及路由

module.exports = {
    title: 'Jessie的个人技术博客',
    description: '办法总比问题多',
    theme: "reco",
    themeConfig: {
        nav: [
            { text: '首页', link: '/' },
            { 
                text: 'Jessie的博客', 
                items: [
                    { text: 'Github', link: 'https://github.com/Jessie-jzn' },
                    { text: 'CSDN', link: 'https://blog.csdn.net/zn740395858?spm=1010.2135.3001.5343' }
                    { text: '掘金', link: 'https://juejin.cn/user/2524134425764375' }
                ]
            }
        ],
        sidebar:[
            {
                title: "博客搭建",
                path: "/construction/Blog1",
                collapsable: false, // 不折叠
                children: [
                    { title: "博客 01", path: "/construction/Blog1" },
                ],
            }
        ]
    }
}

此刻的博客页面效果如下

部署到GitHub

1. 在自己的github上新建一个项目，我这边是叫Jessie-blog
   

2. 回到本地的项目上，在.vuepress/config.js中新增一个 base 路径配置，这个非常重要‼️

module.exports = {
    title: 'Jessie的个人技术博客',
    description: '办法总比问题多',
    base: '/Jessie-blog/', // 这个路径名称就是你刚才所配置的项目名！！！，斜杠不能漏！！！⚠️
    theme: "reco",
    themeConfig: {
        nav: [
            { text: '首页', link: '/' },
            { 
                text: 'Jessie的博客', 
                items: [
                    { text: 'Github', link: 'https://github.com/Jessie-jzn' },
                    { text: 'CSDN', link: 'https://blog.csdn.net/zn740395858?spm=1010.2135.3001.5343' }
                    { text: '掘金', link: 'https://juejin.cn/user/2524134425764375' }
                ]
            }
        ],
        sidebar:[
            {
                title: "博客搭建",
                path: "/construction/Blog1",
                collapsable: false, // 不折叠
                children: [
                    { title: "博客 01", path: "/construction/Blog1" },
                ],
            }
        ]
    }
}

3. 回到本地的项目上，新建一个deploy.sh文件在根目录下，这里需要配置下你自己的git地址和git项目名称和分支。（如果有学习git和工作git想分开配置的话，可以看下我之前写的博客：git操作之一台mac电脑绑定两个git账号，用于工作和学习区分）

#!/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，我学习的git命名是git@study.github.com
git push -f git@study.github.com:Jessie-jzn/Jessie-blog.git master:blog-pages
#git push -f git@github.com:你的git名/你的git项目名.git master:你的git分支

cd -

这就相当于把打包好的dist代码直接放在blog-pages下，到时候在git上配置部署的Source分支为这个字分支就行了，默认就会是渲染index.html

4. 回到github项目上，配置github pages部署的资源，在这里我踩坑了，一开始我只选择了分支，并没有选择是/docs，导致发生vuepress部署在github上出现样式问题，最后发现不能使用默认的/root，而是要改成/docs，😭这个问题让我看了一晚上，一直以为是路径问题

最后生成的地址就是https://jessie-jzn.github.io/Jessie-blog/

基础使用VuePress + GitHub Pages搭建博客也就完成了。

踩坑

如果遇到部署上github后，vuepress样式丢失的情况，请检查

• 是否是路径问题，.vuepress/config.js中的 base 路径是否正常
• github上的资源部署路径是否正确，有没有选对分支，有没有选对资源文件夹

---

github：https://github.com/Jessie-jzn/Jessie-blog