关于vuepress:基于-vuepress-搭建博客教程-自动化部署-GitHub-Actions

介绍

用官网的话来说 VuePress 是一款以 Vue 驱动的动态网站生成器, 它的诞生初衷是为了反对 Vue 及其子项目的文档需要。因为 vuepress 反对自定义开发主题所以很多人拿它来写博客，上面我会用 VuePress 搭建一个极简的博客网站并应用 GitHub Actions 部署到 GitHub Pages。

示例我的项目 github 源码

示例博客拜访地址

搭建博客

前提条件 VuePress 须要 Node.js >= 8.6

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

mkdir vuepress-starter && cd vuepress-starter

1. 应用你喜爱的包管理器进行初始化

yarn init # npm init

1. 将 VuePress 装置为本地依赖

yarn add -D vuepress # npm install -D vuepress

装置依赖留神如果你的现有我的项目依赖了 webpack 3.x，VuePress 官网举荐应用 Yarn 而不是 npm 来装置 VuePress。因为在这种情景下，npm 会生成谬误的依赖树。

1. 创立你的第一篇文档

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

1. 在 package.json 中增加一些 scripts

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

1. 在本地启动服务器

yarn docs:dev # npm run docs:dev

VuePress 会在 http://localhost:8080 启动一个热重载的开发服务器。

如果呈现文章乱码能够参照这篇文章去解决。

当初，你应该曾经有了一个简略可用的 VuePress 文档。如果你有趣味的话能够去 VuePress 官方网站上深刻学习它的配置和用法来丰盛你的网站内容。

部署

部署到 GitHub Pages

接下来的内容假如你曾经应用过 GitHub, 并且对 GitHub Pages 有肯定的理解。

1. 在 GitHub 上创立一个仓库

1. 在 docs/.vuepress/config.js 中设置正确的 base

在 docs/.vuepress 文件夹下创立 config.js

// config.js
module.exports = {base: "/vuepress-starter/"}

1. 配置.sh 脚本

在你的我的项目根目录中，创立一个如下的 deploy.sh 文件（请自行判断去掉高亮行的正文）:

留神
须要将 USERNAME 和 REPO 替换成本人的 GitHub 账号和 仓库名称 这里我拿本人的 GitHub 账号为例。

#!/usr/bin/env sh

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

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

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

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

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

# 如果公布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git main

# 如果公布到 https://<USERNAME>.github.io/<REPO>
git remote add origin git@github.com:huabingtao/vuepress-starter.git
git branch -M main
git push -f git@github.com:huabingtao/vuepress-starter.git main:gh-pages

cd -

以上脚本次要就是干了几件事: 1. 生成动态文件 2. 切换到生成文件的目录下初始化 git 写入一条记录 3. 把动态文件推送到远端仓库的 gh-pages 分支下。

1. 用 sh 脚本部署

关上 package.json 下新增一条命令

"scripts": {
  ...,
  "deploy": "bash deploy.sh"
}

关上控制台执行

npm run deploy

1. 设置仓库 GitHub Pages 拜访门路

当初代码曾经推送到近程仓库的 gh-pages 分支下, 接下来咱们须要设置博客的拜访门路，点击右上角的 Settings 按钮进入设置。

抉择指标分支为 gh-pages, 根目录为 root

稍等几分钟后拜访 https://huabingtao.github.io/vuepress-starter/ 此时发现咱们的博客曾经部署到 Github Pages 了。
到这里如果你只是心愿你的博客能够随时在互联网被拜访到，只须要在写完文章之后去执行 npm run deploy 这行命令就能够了。

应用 Github Actions 主动部署

当初咱们写一篇文章并且公布到 GitHub Pags 须要手动执行 sh 脚本, 应用GitHub Actions 能够帮忙咱们简化流程，让写完一篇文章后只须要将代码上传至 GitHub 就能帮咱们主动构建部署到线上。

GitHub Actions 有一些本人的术语。

1.workflow（工作流程）：继续集成一次运行的过程，就是一个 workflow。

2.job（工作）：一个 workflow 由一个或多个 jobs 形成，含意是一次继续集成的运行，能够实现多个工作。

3.step（步骤）：每个 job 由多个 step 形成，一步步实现。

4.action（动作）：每个 step 能够顺次执行一个或多个命令（action）。

想要理解更多 Github Actions 常识能够浏览官网 GitHub Actions 疾速入门, 或者阮一峰老师的 GitHub Actions 入门教程

创立集体拜访令牌

1. 在任何页面的右上角，单击您的个人资料照片，而后单击 Settings（设置）

2. 在左侧边栏中，单击 Developer settings。

3. 在左侧边栏中，单击 Personal access tokens（集体拜访令牌）

4. 单击 Generate new token（生成新令牌）。
5. 给令牌一个描述性名称。

   令牌名字肯定要叫：ACCESS_TOKEN

6. 抉择要授予此令牌的作用域或权限。要应用令牌从命令行拜访仓库，请抉择 repo（仓库）。

1. 单击 Generate token（生成令牌）。
2. 单击复制将令牌复制到剪贴板。出于平安起因，来到此页面后，您将无奈再次看到令牌。

编写 workflow 文件

工作流文件应用 YAML 语法，这里不对 YAML 语法做过多介绍想要理解更多信息请参阅五分钟理解 YAML。

接着创立 .github/workflows/main.yml 文件, 内容如下:

name: docs

on:
  # 每当 push 到 main 分支时触发部署
  push:
    branches: [main]
  # 手动触发部署
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
        with:
          #“最近更新工夫”等 git 日志相干信息，须要拉取全副提交记录
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          # 抉择要应用的 node 版本
          node-version: "14"

      # 缓存 node_modules
      - name: Cache dependencies
        uses: actions/cache@v2
        id: yarn-cache
        with:
          path: |
            **/node_modules
          key: ${{runner.os}}-yarn-${{hashFiles('**/yarn.lock') }}
          restore-keys: |
            ${{runner.os}}-yarn-

      # 如果缓存没有命中，装置依赖
      - name: Install dependencies
        if: steps.yarn-cache.outputs.cache-hit != 'true'
        run: yarn

      # 运行构建脚本
      - name: Build VuePress site
        run: yarn docs:build

      # 查看 workflow 的文档来获取更多信息
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@3.7.1
        with:
          ACCESS_TOKEN: ${{secrets.ACCESS_TOKEN}}
          # 部署到 gh-pages 分支
          BRANCH: gh-pages
          # 部署目录为 VuePress 的默认输入目录
          FOLDER: docs/.vuepress/dist

以上代码次要配置内容如下:

1. branches 代表 git push 触发 flow 的分支名称，如果你的分支不是 main 请批改正确。
2. run 示意运行命令，若没有批改的话就是 yarn docs:build。
3. ACCESS_TOKEN 读取 GitHub 仓库之前咱们设置的 ACCESS_TOKEN，名称肯定要与之前设置的雷同。
4. BRANCH 部署到 gh-pages 分支下。
5. FOLDER 部署目录, 如果没有批改默认配置就是 docs/.vuepress/dist。

实现以上配置，下次 push 代码的时候，就会主动开启构建。

尝试 push 代码，回到 GitHub 上点击 actions, 发现我的项目曾经在主动构建了。

点击进入查看部署状况。

部署胜利，如果构建失败 GitHub 会发送一封邮件到你的邮箱。

搭建过程中遇到的问题

1. 如果你打算公布到 https://<USERNAME>.github.io/， 则不须要配置 .vuepress/config.js base 属性, 因为 base 默认是 “/”。
2. 公布到线上后发现 css 款式失落，经查看发现拜访门路产生 404 的有可能是我的项目援用门路谬误，本文没有批改过打包门路，用的是默认门路 docs/.vuepress/dist，如不统一请批改。
3. 本文所应用的 actions 版本是 v3，以往教程中所讲到的应用的是JamesIves/github-pages-deploy-action v2 版本，新版本语法曾经产生了变动，如果持续应用就会产生谬误。
4. ACCESS_TOKEN 肯定要和 github 上的 sectets 上的名称雷同。

参考资料

• vuepress 官网
• 应用 GitHub Actions 主动部署博客
• 阮一峰 GitHub Actions 入门教程
• MarkDown 根本语法

小结

本文介绍了如何应用 vuepress 搭建博客，并应用 GitHub Pages 部署到线上环境，然而部署的流程都是手动操作的有些麻烦，文章后半局部内容简略介绍了GitHub Actions，实现了当咱们要公布一篇文章的时候只有push 到 GitHub 就能实现自动化打包公布流程，让双手从机械的流程中解脱专一于写作。尽管可能简略实现一个博客网站，然而 VuePress 的更乏味的玩法还有待大家本人去学习。

以上就是本篇文章的所有内容。最初，感谢您浏览这篇文章，有任何问题或反馈请给我留言。