Vuepress 搭建静态博客全攻略

想在两个小时以内搭建出来一个带有评论系统和谷歌数据分析的静态博客，同时完成静态博客的自动构建和部署吗🚀？

这篇文章对每一个步骤都作了详细的记录，还把每一个步骤中踩过的坑梳理了出来，，绝对能够给你提供不少帮助～

后续我还会加上「复制博客文章内容加上版本信息」、「全文检索」等功能，敬请期待💪

博客的最终效果能够看这里

Vuepress 搭建静态博客

能够参照 Vuepress 的官方文档 一步一步来就行了，我这里就简单说下步骤：

1. 安装 Vuepress

你能够全局安装：

# 可使用 npm 来全局安装
npm i -g Vuepress

# 也可使用 yarn 来全局安装
yarn global add Vuepress
复制代码

也能够安装在你静态博客项目的开发依赖里面:

yarn add --dev Vuepress

# 或者
npm i -D Vuepress
复制代码

2. 初始化博客项目

# 可使用 npm 来初始化项目
npm init

# 也可使用 yarn 来初始化项目
yarn init
复制代码

而后在项目的根目录下新建一个 docs 文件夹，之后咱们写的 markdown 文件都会放在 docs 文件夹下。

咱们先随便初始化一个文件来看看效果：

echo '# Hello VuePress!' > docs/README.md
复制代码

执行命令 vuepress dev docs

能够看到启动了一个页面：

为了后续运行方便，咱们能够把这些命令写在项目的 package.json 文件里面的 scripts：

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },
 }
复制代码

3. 进一步的配置

目前咱们只写了一个 markdown 文档，因此只有一个页面，后续咱们的博客会陆续加入不少内容，确定须要作目录分级，配置导航栏，能够看文档里的这部分

4. 部署

静态博客搭好了，咱们就能够把它部署到服务器上正式给别人访问了，你可使用 GitHub Pages（GitHub 的静态页面托管服务 ）来托管本身的静态博客。 可使用 gh-pages 来将打包好的静态博客快速部署到 GitHub Pages 上。

一样的，咱们能够将部署的命令加入到 package.json 文件里面的 scripts，如今，咱们的 scripts 就是这样的：

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs",
    "deploy": "npm run build && gh-pages -d docs/.vuepress/dist"
  },
 }
复制代码

您也可使用其余第三方静态页面托管服务（如 Netlify、Coding Pages、Gitlab Pages 等），这篇文章里面介绍了不少免费的静态页面托管服务。

到这一步，你的博客已经能够顺利地运行、构建和部署了，直接执行 npm run deploy 就能够将您的博客部署到 GitHub Pages 上去，若是您还想让你的博客书写和使用的体验更好，能够接着往下看。

GitHub Actions 自动构建/部署

你们有注意到 GitHub 悄悄上线了一个 Actions 功能吗？还不了解的同窗能够看这篇文章，写的很是全面。

GitHub Actions 是什么呢？GitHub 官方号称 Actions 可让你的**工做流自动化**：GitHub 监听某个事件（多是某个分支的提交），而后触发你预约义的工做流，让你们在GitHub服务器上直接测试代码、部署代码。因此，咱们能够利用这里特性来作 CI/CD，开发者只要写一下 workflow 脚本就能够了，不用费心思去想要用哪一个第三方的 CI/CD 服务。

actions 其实就是由一些脚本组成，因此它们是能够复用的，GitHub 作了一个官方市场，能够搜索到他人提交的 actions。另外，还有一个 awesome actions 的仓库，也能够找到很多 action。这样一来，你甚至都不用本身写具体的脚本，直接引用别人的脚本就行啦。

话很少说，赶忙用起来！

写 workflow 脚本

首先咱们须要到项目仓库的页面上进入 Actions 这个 tab, 选择 Node 环境进入脚本的编辑页面

这里我直接使用了 peaceiris 的 actions-gh-pages，这个 action 能够帮你把打包好的静态文件部署到 GitHub Pages 上去。

最终个人 workflow 脚本以下：

这里有个人 脚本源文件，能够参考一下。

更详细的语法能够去看 GitHub Actions 的官方文档

注意⚠️

由于我用的 action 是第三方的，因此 action 可能会常常更改，若是你是过了一段时间才看到这篇文章，peaceiris 的 actions-gh-pages 极可能已经发生了更新，因此脚本的内容建议直接参照它的官方文档来写。

设置 workflow 的环境变量

上面的脚本里面第21行的环境变量是怎么回事呢？

由于咱们须要 GitHub Actions 把构建成果发到 GitHub 仓库，所以须要 GitHub 密钥，至关因而给 GitHub actions 受权。

首先运行下面的命令生成一对密钥：

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
# You will get 2 files:
# gh-pages.pub (public key)
# gh-pages (private key)
复制代码

而后：

1. 在博客项目的仓库的 Settings 栏下，找到 Deploy keys这一项，把你的公钥加进去，注意勾选Allow write access
2. 一样在博客项目的仓库的 Settings 栏下，找到 Secrets这一项，把你的私钥加进去

   

注意事项

1. 把 Vuepress 做为你的开发依赖加入到项目的 package.json 文件里面进行管理。（不然在 GitHub 的 docker 容器里打包的时候会找不到 Vuepress 这个命令）
2. 使用 npm 而不是 yarn 来管理依赖包。（由于 npm 是 node 环境自带的包管理工具，无需额外安装，另外， peaceiris 的 actions-gh-pages 也是使用 npm 做为包管理工具的）
3. 使用 npm ci 来安装依赖包，而不是 npm install

npm ci 和 npm i 的区别能够看 medium 上的这篇文章 了解一下。

简单来讲就是：不像npm install，npm ci永远不会修改您的package-lock.json，它的使用依赖于 package-lock.json文件。因此若是使用npm ci，您将得到可靠的版本。一般这个命令会在 Jenkins或GitLab CI之类的持续集成工具中使用。

好了，这样每次你的项目 master 分支一旦有新的提交，就会自动触发这个 workflow，就能够自动完成静态博客的构建和部署了～

也就是说，咱们能够直接利用 GitHub 的 markdown 编辑器，直接新建一个文档进行协做，而后提交到 master 分支就好了，彻底不用再次去作 git 提交以及本地的构建和部署，简直太方便了 :rocket:

添加评论系统

搭建博客的目的确定是为了能和更多技术同好交流，因此评论系统是不可或缺的一个功能。

咱们可使用 gitalk 这个开源的评论插件来作博客的评论系统，它是基于 GitHub Issue 来开发的，能够直接使用 GitHub 帐号登陆，这对程序员来讲真的是至关友好了👬

注册 GitHub OAuth Application

首先要申请一个 GitHub OAuth Application。能够点击这里申请.

注意:

Authorization callback URL 必定要填写当前使用插件页面的域名。

注册成功后你会获得一个 Client ID 和 Client Secret，这两个数据咱们下一步要用到。

建立评论组件

咱们回到工程，在 docs/.vuepress 下新建一个文件夹 components，再在 components 文件夹下建一个 comment 文件夹，而后新建文件 comment.vue，并复制下面的代码。

<template>
  <div class="gitalk-container">
    <div id="gitalk-container"></div>
  </div>
</template>
<script> export default { name: 'comment', data() { return {}; }, mounted() { let body = document.querySelector('.gitalk-container'); let script = document.createElement('script'); script.src = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js'; body.appendChild(script); script.onload = () => { const commentConfig = { clientID: 'YOUR_CLINENT_ID', clientSecret: 'YOUR_CLINENT_SECRET', repo: '此仓库的名称', owner: '你的 GitHub 用户名，注意是用户名！！！', // 这里接受一个数组，能够添加多个管理员 admin: ['你的 GitHub 用户名'], // id 用于当前页面的惟一标识，通常来说 pathname 足够了， // 可是若是你的 pathname 超过 50 个字符，GitHub 将不会成功建立 issue，此状况能够考虑给每一个页面生成 hash 值的方法. id: location.pathname, distractionFreeMode: false, }; const gitalk = new Gitalk(commentConfig); gitalk.render('gitalk-container'); }; }, }; </script>
复制代码

注意:

id 不能超过50个字符，不然后续评论组件初始化的时候会发生Error：validation failed 的报错。

你可使用较短的字符来做为 id，例如我本身是使用 document.title.replace(/\s\|\s去冲浪鸭|《|》/g, "")来做为 id 的，即便用个人文章标题做为 id。

配置组件

在工程根目录下新建一个文件夹 builds，并在里面新建三个文件，分别是 findMarkdown.js, addComponents.js 和 delComponents.js。

findMarkdown.js 文件读取你全部的 Markdown 文件的内容。

// findMarkdown.js
const fs = require('fs')

function findMarkdown(dir, callback) {
  fs.readdir(dir, function (err, files) {
    if (err) throw err

    files.forEach((fileName) => {
      let innerDir = `${dir}/${fileName}`

      if (fileName.indexOf('.') !== 0) {
        fs.stat(innerDir, function (err, stat) {

          if (stat.isDirectory()) {
            findMarkdown(innerDir, callback)
          } else {
            // 跳过readme 文件，固然你也能够自行修改
            if (/\.md$/.test(fileName) && !/README/.test(fileName))
              callback(innerDir);
          }
        })
      }

    })
  })
}

module.exports = findMarkdown
复制代码

addMarkdown.js 文件将 comment 组件注册到每一个 Markdown 文件的最后。

// addMarkdown.js
const fs = require('fs')
const findMarkdown = require('./findMarkdown')
const rootDir = './docs'

findMarkdown(rootDir, writeComponents)

function writeComponents(dir) {
  if (!/README/.test(dir)) {
    fs.appendFile(dir, `\n \n <comment-comment/> \n `, (err) => {
      if (err) throw err
      console.log(`add components to ${dir}`)
    })
  }
}
复制代码

delMarkdown.js 文件在编译后执行，目的是将每一个 Markdown 文件的 comment 组件移除，由于咱们只想让 comment 组件打包到编译后的文件中，而非工程文件。

// delMarkdown.js
const fs = require('fs')
const findMarkdown = require('./findMarkdown')
const rootDir = './docs'

findMarkdown(rootDir, delComponents)

function delComponents(dir) {
  fs.readFile(dir, 'utf-8', (err, content) => {
    if (err) throw err

    fs.writeFile(dir, content.replace(/\n \n <comment-comment\/> \n /g, ''), (err) => {
      if (err) throw err
      console.log(`del components from ${dir}`)
    })
  })
}
复制代码

修改构建脚本

修改 build 的脚本：

{
  "build": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js"
}
复制代码

好了，这样你的博客就有一个评论系统了，效果以下：

每次有人在一篇评论数为0的文章下面评论，就会自动以当前文章为标题，当前文章的网址为内容生成一条 GitHub Issue，评论就会被关联到这条 GitHub Issue 上。

配置全文搜索

待补充...

配置 Google Analytics

博客搭建好了，也有人访问了，那咱们要怎么统计用户的访问状况呢？可使用谷歌出品的 Google Analytics （GA）。

Google Analytics （GA）是一个对用户活动进行追踪的工具，利用 GA 咱们能够收集到博客当前有多少实时活跃用户，博客的总访问量，以及分析用户的一些访问行为，便于咱们对博客网站作一些优化，并且它仍是免费的！赶快用起来！

下载 google-analytics 插件

Vuepress 官方已经为咱们准备好了 google-analytics 插件。

yarn add -D @vuepress/plugin-google-analytics
# OR npm install -D @vuepress/plugin-google-analytics
复制代码

安装完在 config 配置文件里面配置一下 plugins

module.exports = {
  plugins: [
    [
      '@vuepress/google-analytics',
      {
        'ga': '' // UA-00000000-0
      }
    ]
  ]
}
复制代码

注册 GA，获取追踪 ID

上面那个 ga ID从哪里获取呢？别着急，咱们须要到 Google Analytics 的官网上去注册一下咱们的博客应用：

进去后选择 web app:

把获取到的跟踪ID 填到上面👆的ga这一项里面就行了。

给 Vuepress 博客作 SEO 优化

待补充...

复制文字时显示版权信息

待补充...