VuePress搭建博客与自动部署

大风起兮云飞揚
925 阅读6分钟

    之前有迁移博客的想法 这两天折腾了下，将原来的手写博客，迁移到利用VuePress构建，目前已经实现了基本结构，以及利用githubPages托管站点 以及利用githubActions持续集成,避免每次都手动构建,这其中也趟了不少坑，好在整个流程算是跑下来了。

  其中主要经历了这几步: 下面会把每一步的实现具体写一下

  1. 创建vuePress项目
  2. 目录配置
  3. 利用githubPages进行部署
  4. 利用githubActions workflows 持续集成

1.创建vuePress项目

mkdir vuepress-starter && cd vuepress-starter  // 创建文件夹

yarn init  // 初始化

yarn add -D vuepress  // 本地安装 vuePress

// 创建一个目录名为docs的文件夹 并创建一个README.md的文件 随便写上内容
mkdir docs && echo '# Hello VuePress' > docs/README.md 

// 在package.json添加如下命令
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

// 启动项目
yarn docs:dev

打开访问浏览器的8080 可以看到项目已经启动成功了

2.目录配置

  1. 创建.vuepress文件夹在docs目录下
  2. 新建一个config.js的文件
  3. 写自己设计的目录

image.png

目前的目录结构应该是这样 可以忽略其他文件夹 ，然后我们在config.js文件夹写一些东西

module.exports = {
     title: '飞扬的博客'
}

保存这时我们在预览界面 左上角就会有我们刚才设置的title 效果如下 忽略右边

image.png

config.js中的 themeConfig对象 给出了如下两个key字段

nav: 配置头部导航

sidebar: 配置左侧目录

下面我们分别在这两个配置中写上一些配置

module.exports = {
    title: '飞扬的博客'，
    nav:[
        {
         text: "前言概述",
         link: "/"
        },
        {
          text: "聊聊前端",
          link: "/frontend/"
        }
    ],
    sidebar: {
     '/frontend/': [
       {
         title: '学习大纲',
         path: '/frontend/PATH'
       },
       {
         title: '前端秘籍',
         path: '/frontend/'
       },
       {
         title: 'JavaScript',
         children: [
           {
             title: '前言',
             path: 'javascript/'
           },
           'javascript/原型链'
         ]
       }
     ],
     '/java/': [
       {
         title: '学习路线',
         path: '/java/'
       }
     ]
   }
}

nav: 是一个数组对象的形式 对象的text字段 是导航显示的文字，对象的link字段是要进行索引的文件夹目录，为绝对路径 这里需要注意的地方是写上的link要和文件夹名称对应 这是VuePress约定的规则。

sidebar: 接受Array/Object的形式，这里我使用的是Object, 参照上面的配置此时我在头部导航点击了 /frontend/ 这个路径 那么则需要在sidebar定义一个值为这个路径的key，例如上面的 /frontend/ 且因为这个路径下可能包含其他小模块，所以我定义值为数组，数组的每一项有两个key，一个表示我们左侧显示的菜单名称，另一个表示跳转的链接。

这时我们可以在docs创建如下目录我们定义的菜单项的目录 如下图

image.png

image.png

    下面来解释一下上面这段代码的意思，当我们点击nav中的 聊聊前端 的时候，会根据link属性，去找sidebar下相应的key，如果找到，则渲染相该key对应的数组内容，当点击左侧菜单的某一项时 则根据path去找对应的文件，默认寻找的是README.md文件,例如当我们点击了前端秘籍,则寻找frontend/README.md 否则就应该在path中写上具体的文件名称。然后就是愉快的写内容了 (我这么说你们能懂吧 Ps:可怜)。

3.利用githubPage进行部署

     原理就是不用你自己的域名服务器，你只需要创建一个git账号，上传代码，利用git托管之后，就可以进行线上访问了。

首先我们要把刚才写的代码上传到git上，上传步骤我就省略了

image.png

然后我们新建一个配置文件 deploy-gh.sh

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

# 把上面的 <USERNAME> 换成你自己的 Github 用户名，<REPO> 换成仓库名，比如我这里就是：
git push -f https://github.com/USERNAME/<REPO>.git master:gh-pages

cd -

注意我们还需要改一处东西 这个base字段一定要和我们git的仓库名称一样

image.png

添加一个命令行 并执行

image.png

如果是正在构建中 可以看到这个目前是黄色的loading image.png

构建完成这里应该是绿色的 恭喜你绿了 image.png

截止到这一步 我们就可以在浏览器访问我们的项目了 下面的链接需要把仓库名和用户名替换成你自己相对应的。

[USERNAME.github.io/REPO/fronte…]

4.持续集成

     其实上面的步骤执行完毕之后 我们就已经可以进行正常的构建和部署了 但是如果频繁的更新项目就需要频繁的执行打包命令，所以调研了一下是否有持续集成的方案，好在github提供了这个东西。

  1. 我们在docs 文件夹下新建一个.github的文件夹, 然后新建一个workflows的文件夹,
  2. 新建一个xxx.yml的配置文件 贴上如下配置
name: Deploy GitHub Pages

# 触发条件：在 push 到 main 分支后
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
# 任务
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          persist-credentials: false

      - uses: actions/cache@v2.1.4
        id: node-modules
        with:
          path: node_modules/
          key: ${{ runner.os }}-node-modules-${{ hashFiles('yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-node-modules-

      - name: Install Deps
        if: steps.node-modules.outputs.cache-hit != 'true'
        run: yarn install --frozen-lockfile

      - name: Build Template
        run: yarn run docs:build

      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@4.2.0
        with:
          ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          BRANCH: gh-pages
          # 部署目录为 VuePress 的默认输出目录
          FOLDER: docs/.vuepress/dist

最坑的点要来了，在这里耽误了将近一下午的时间

分支名一定要注意区分 我这里是main分支

JamesIves/github-pages-deploy-action@4.2.0 网上大多数版本

JamesIves/github-pages-deploy-action@releases/v3 官方issuse

这句配置是最坑的地方,由于是参考网上的一些文章,其中版本都比较老,所以在配置文件中都是写的下面的配置，然后在构建的时候就会报下面的错，解决办法都参差不齐，并没有效果

image.png

还是参考了官方的issue 把配置替换成新的版本 才可以成功构建, 这样我们每次提交代码 都会自动帮我们进行构建,然后更新网站,如下图

image.png

吐槽一下,遇到问题,尽量去看官方的issue,搜索引擎并不是每次都可以解决你的问题 相反会耽误你的时间

好了,到这里本篇文章的基本要阐述思路的内容,就表达完了。

[仓库地址在] github.com/chongyangwa…

[预览地址] chongyangwang.github.io/blog-docs/

文章参考

avatar
文章
阅读
粉丝