一个字：坑，两个字：很坑，三个字：很多坑。

温馨提示

如果你正在寻找 VuePress 搭建博客的教程，建议首先查看最后的 总结 部分。

📋 目录

# 关于 VuePress

VuePress(opens new window) 是一个由 Vue(opens new window) 驱动的极简静态网站生成器，由 尤雨溪(opens new window) 开发。我第一次知道 VuePress 是看见少数派作者 SpencerWoo(opens new window) 的博客，一下就被其简洁大气的风格吸引住了，决定我也要建一个这样的网站[1]，甚至还立下了一个 Flag。

之前我一直没空，顾不上折腾，用着 Gridea(opens new window) [2] 也还行。眼看 Flag 就要倒了，然而 10 月下旬我重装了电脑系统，忘记了备份 Gridea 的配置[3]和写过的文章[4]，于是就不得不开始折腾 VuePress 了。

实际上，VuePress 官方文档(opens new window) 写得非常详细，同时我使用的主题 Meteorlxy(opens new window) 的使用指南也很清楚明白。虽然如此，但在整个过程中，我还是遇到了很多坑。因此，与其说这是一篇 VuePress 博客搭建指南，倒不如说是一份「避坑指南」。

# 安装 VuePress

VuePress 指南(opens new window) 中有 2 种安装方式，分别是全局安装和本地依赖安装，我选择的是本地依赖安装：

# 在桌面新建一个 blog 文件夹
cd desktop
mkdir blog
# 进入 blog 文件夹
cd blog
# 将 VuePress 作为一个本地依赖安装
yarn add -D vuepress # 推荐安装方式
# 或者使用 npm 安装，但不推荐！
# npm install -D vuepress
1
2
3
4
5
6
7
8
9
10
11

# npm 那些坑

官方文档提到，如果现有项目依赖了 webpack 3.x，推荐使用 Yarn(opens new window) 而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。但我没有现有项目，因此还是使用了 npm，然而这就为后面的坑埋下了隐患。

提示

使用 npm 前，需要安装 Node.js(opens new window) 。

其实使用 npm，按照 VuePress 官方文档和 Meteorlxy 使用指南，是没有问题的，能够在本地生成（dev）和构建（build）静态资源。问题就出在插件上，用 npm 安装插件会替换掉 VuePress 的很多文件，导致 VuePress 框架内容的缺失，无法正常工作。

比如我要安装一个 vuepress-plugin-mathjax 插件，用来支持 数学公式，按照安装指南，执行下列命令进行安装：

cd desktop/blog
npm i vuepress-plugin-mathjax
1
2

然而安装好之后，原来超过 100MB 的文件夹 node_modules 就变成 20MB 左右了，因为文件夹里的很多内容被替换或移除掉了，这样肯定是不行的。当时我困惑了老半天，一直找不到解决办法。后来，换成用 Yarn 安装，终于就没有问题了，所以 npm 是真的坑啊。

# 避坑指南一

重要的事情说三遍

不要使用 npm！不要使用 npm！不要使用 npm！

使用 Yarn 安装 VuePress 及相关主题、插件（后文将全部使用 Yarn）

# 进入桌面上的 blog 文件夹
cd desktop/blog
# 一次性安装 VuePress，Meteorlxy 主题以及 3 个插件：vuepress-plugin-feed（生成 RSS 订阅）、markdown-it-footnote（支持 Markdown 脚注）、markdown-it-katex（Markdown 中使用数学公式）
yarn add -D vuepress vuepress-theme-meteorlxy vuepress-plugin-feed markdown-it-footnote markdown-it-katex
1
2
3
4
5

提示

上述安装操作前需安装 Yarn。如何安装 Yarn，可前往 Yarn 官网(opens new window) 查看。

# 插件那些坑

安装了 markdown-it-footnote、markdown-it-katex 等插件，在 .config.js 中也配置好之后，插件还是没有生效，我就很纳闷，于是上网四处搜索，看哪里没弄对。看了很多搜索结果之后，终于，通过 Google 搜索，找到 VuePress 仓库的 issues#597(opens new window) 下的一个 回复(opens new window) ，其中有一个 链接(opens new window) 提到，在 VuePress 1.x 版本(opens new window) [5]中，必须使用 extendMarkdown 而不能使用 config。

# 避坑指南二

使用 extendMarkdown 在 docs/.vuepress/config.js 中配置插件：


 





markdown: {
      extendMarkdown: md => {
          md.use(require("markdown-it-footnote"));
          md.use(require("markdown-it-katex"));
      },
  }
1
2
3
4
5
6

# 部署那些坑

VuePress 指南关于 部署(opens new window) ，也比较详细。但是，按照这个操作，我一直没有部署成功，试了好多次之后，才发现我一直多写了一行构建代码 yarn dev，而在部署中这一步是不需要的，只需要 yarn build 就可以了。

# 避坑指南三

新建一个文件 deploy.sh 文件，在其中写入如下代码，然后保存。

#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 构建静态文件
yarn build
# 进入生成的文件夹
cd dist
# 发布到自定义域名，没有可注释掉
echo 'example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 发布到 https://<USERNAME>.github.io
git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master
# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages
cd -
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

运行上面这个 deploy.sh 文件，就会生成静态资源 dist，并将这个文件夹里的所有内容推送到 GitHub 上去，可参考下方的动图。

至此，将 VuePress 生成的静态资源推送至 GitHub，一个基本完整的博客就搭建完成了。接下来的自动部署是可选操作，属于锦上添花的步骤。

# 自动部署博客

有用户曾在 Gridea 用户群里询问开发者 海岛心hey(opens new window) 有没有可能开发移动端应用，我记得开发者回复说没有这个打算，因为 Gridea 需要 Git 的支持，移动端无法实现，但是 iOS & iPadOS 上不就有 Working Copy 这样的全能型 Git 客户端吗？

折腾了 VuePress 之后，我进一步理解了静态网站生成的步骤：首先由博客框架[6]把写好的 Markdown 文件生成为包含 .html、.css、.js 等内容的静态资源，然后由 Git 将这些静态资源推送至 GitHub、GitLab 等代码托管平台，用户即可通过域名访问。因此，我觉得目前来说，Gridea 没有移动端，不是因为没有 Git，而是不能在移动端使用博客框架生成静态资源[7]，因而无法实现「随时随地」[8]更新博客。

而使用 VuePress，可以实现随时随地更新博客吗？答案是可以！

借助 Travis CI 可以实现博客自动部署。Travis CI(opens new window) 是一个构建和测试的自动化工具，提供的是持续集成服务（Continuous Integration，简称 CI），它只支持 GitHub。通过将 Travis CI 和 GitHub 上的项目绑定，只要项目中的代码有变动，Travis CI 就会自动抓取，然后提供一个运行环境，执行测试，完成构建，部署到服务器。

简单来说，Travis CI 完成的就是 deploy.sh 所做的事情，只不过由本地搬到了服务器上[9]。有了 Travis CI，只需要将 blog 文件夹创建为一个 Git 仓库或者 Git 仓库的一个分支，像普通文件一样修改里面的内容，然后将其推送到 GitHub 上去，剩下的事情就交给 Travis CI 了。

# 配置 Travis CI

  1. 访问 Travis CI(opens new window) ，使用 Github 账号登录
  2. 选择你需要 Travis CI 监控的仓库，就是博客源码所在仓库，比如这里的 blog
  3. 在本地的 blog 文件夹下新建一个 .travis.yml 文件，写入下面的内容，然后保存
language: node_js
node_js:
  - stable
cache:
  directories:
  - "node_modules"
install:
  - yarn
script:
  - ./deploy.sh
branch: master
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
  1. 前往 Github Setting(opens new window) 生成一个 Personal access tokens
  2. 修改 deploy.sh

把其中的：

git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master
1

修改为：

git push -f https://<Personal access tokens>@github.com/<USERNAME>/<USERNAME>.github.io.git master
1

在电脑端，每次修改完之后，只需将整个 blog 文件夹 push 到 GitHub 就完事了，剩下的构建和部署都将由 Travis CI 来完成。一般 push 完成后 2 分钟左右，博客就会更新完成。

# iOS & iPadOS 上更新博客

在 iPhone 或 iPad 上下载 Working Copy(opens new window) [10] 这个 App，登录 GitHub 账号，然后 clone 下来博客所在仓库，修改 _posts 文件夹下的文章[11]，然后 commit 并 push 就完成了博客更新，实现随时随地更新博客✌️

# 总结

  1. 安装 Yarn（以 macOS 为例）
brew install yarn
1
  1. 使用 Yarn 一次性安装 VuePress、Meteorlxy 主题和相关插件
# 在桌面上新建 blog 文件夹
cd desktop
mkdir blog
# 进入 blog 文件夹
cd blog
# 安装 VuePress、Meteorlxy 主题和相关插件
yarn add -D vuepress vuepress-theme-meteorlxy vuepress-plugin-feed markdown-it-footnote markdown-it-katex
1
2
3
4
5
6
7
8
9
  1. 在 package.json 加入 scripts 字段
{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs --dest dist"
  }
}
1
2
3
4
5
6
  1. 配置 docs/.vuepress/config.js（可根据示例进行修改）
点击展开配置示例☞(ﾟヮﾟ)☜ 
// .vuepress/config.js
const feed_options = {
  canonical_base: 'https://example.com',
};
module.exports = {
  title: 'Your Name',
  description: 'Some Descriptions',
  head: [
    ['link', {rel: "icon", href: "/assets/img/favicon.ico"}],
  ],
  locales: {
    '/': {
      lang: 'zh-CN',
    },
  },
  markdown: {
      lineNumbers: true,
      extendMarkdown: md => {
          md.use(require("markdown-it-footnote"));
          md.use(require("markdown-it-katex"));
      },
  },
  plugins: [
    ['@vuepress/google-analytics', {
      ga: 'UA-xxxxxxxxx-1', // Google Analytics
    }],
    [
     'feed', feed_options
    ],
  ],
  theme: 'meteorlxy',
  themeConfig: {
    lang: 'zh-CN',
    personalInfo: {
      nickname: 'Nickname',
      description: 'Some Descriptions',
      email: '[email protected]',
      location: 'Hangzhou, China',
      organization: 'Zhejiang University',
      avatar: '/images/avatar.png',
      sns: {
        github: {
          account: 'GitHub-Account',
          link: 'https://github.com/GitHub-Account',
        },
        twitter: {
          account: 'Twitter-Account',
          link: 'https://twitter.com/Twitter-Account',
        },
        weibo: {
          account: 'Weibo-Account',
          link: 'https://www.weibo.com/u/0123456789',
        },
    header: {
      background: {
        useGeo: true,
      },
      showTitle: true,
    },
    footer: {
      poweredBy: true,
      poweredByTheme: true,
      custom: 'Custom Words',
    },
    infoCard: {
      headerBackground: {
        useGeo: true,
      },
    },
    lastUpdated: false,
    nav: [
      { text: 'Home', link: '/', exact: true },
      { text: 'Posts', link: '/posts/', exact: false },
      { text: 'About', link: '/about/', exact: true },
      //{ text: 'Custom Pages', link: '/custom-pages/', exact: false },
    ],
    comments: false,
    pagination: {
      perPage: 10,
    },
    defaultPages: {
      home: true,
      posts: true,
    },
  },
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
  1. 自动部署

在本地的 blog 文件夹下新建一个 .travis.yml 文件，写入下面的内容，然后保存。访问 Travis CI(opens new window) ，使用 Github 账号登录，选择你需要 Travis CI 监控的仓库，这里就是 blog。

language: node_js
node_js:
  - stable
cache:
  directories:
  - "node_modules"
install:
  - yarn
script:
  - ./deploy.sh
branch: master
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

前往 Github Setting(opens new window) 生成一个 Personal access tokens。新建 deploy.sh，写入下面的内容，然后保存。

#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 构建静态文件
yarn build
# 进入生成的文件夹
cd dist
# 发布到自定义域名，没有可注释掉
echo 'example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
git push -f https://<Personal access tokens>@github.com/<USERNAME>/<USERNAME>.github.io.git master
cd -
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

按照上述步骤设置完成之后，更新博客只需要简单几步：

  1. edit：编辑文件
  2. add：暂存更新
  3. commit：提交更新
  4. push：推送更新
  5. 完成！[12]

按照以上操作步骤，有可能还是会出现各种问题，但只要细心一点、耐心一点，总是会成功的！

最后再画一个流程图，测试一下 vuepress-plugin-flowchart(opens new window) [13]。

  1. 其实吸引我的是博客的主题，像我这样的博客初级玩家玩的就是主题啊～ ↩︎

  2. 其实 Gridea 的网站就是用 VuePress 搭建的。 ↩︎

  3. 在重装系统前几个月我就开始备份电脑中重要的文件，包括 Typora 的主题、Visual Studio Code 的配置、Alfred 的设置文件等，但唯独忘记了 Gridea，真是老天不要我的 Flag 倒下啊。。。 ↩︎

  4. 为了找回以前的文章，我还去扒了自己的博客。。。 ↩︎

  5. VuePress 有 0.x 和 1.x 两种版本，我安装的版本是 VuePress 1.2.0，默认安装 1.x 版本。 ↩︎

  6. 比如 Hexo(opens new window) 、Hugo(opens new window) 、VuePress(opens new window) 、Gridea(opens new window) 等。 ↩︎

  7. 顺便一提，也有网友 使用 Caddy 自动部署 Gridea 博客(opens new window) 。 ↩︎

  8. 注：「随时随地」意为可以通过移动端而不依靠桌面设备进行更新。 ↩︎

  9. 这就为在 iOS 或 iPadOS 上更新博客创造了条件。 ↩︎

  10. Working Copy 应用本身免费，解锁内购需 ¥108。如果你的 GitHub 账号通过了学生认证，可以打开 这个页面(opens new window) ，点击跳转到 Working Copy 中用 GitHub 账号登录，即可免费解锁 Working Copy 所有功能。 ↩︎

  11. Working Copy 应用内的编辑体验不是特别好，可以选择在 Textastic(opens new window) 、iA Writer(opens new window) 、MWeb(opens new window) 等应用中打开进行编辑。 ↩︎

  12. 在 Visual Studio Code(opens new window) 中一气呵成完成全部步骤，是真的香 😋 ↩︎

  13. 2019 年 11 月 10 日添加的插件。 ↩︎