语雀云端写作

发表于 更新于 分类于 阅读次数： 本文字数： 15k 阅读时长 ≈ 14 分钟

语雀云端写作实现了 Markdown 格式的博文与博客构建目录的分离，这样的话，我想同时使用多少个主题都是没有问题的了，更重要的事，可以完全实现静态博客在线编辑。

本文对于文件（代码）变动的描述方式为-指删掉该行，+指增加改行（如果你是直接复制此行，请注意删掉+和上下文对齐），...表示省略上下文。另外，本文对于文件（代码）变动的描述只针对当时的文件（代码）版本，请根据实际情况决定对自己的相应文件（代码）进行变动。

博文迁移

首先是注册语雀账号，登陆上后，新建知识库，名称就为个人博客，再点击右上方的新建，选择导入，选择 Markdown 格式，将本地博文（即 _post 下的 Markdown 文件）批量（按住 Ctrl 可多选）导入至知识库个人博客。

导入成功后会发现每篇博文的开头，即 front-matter 部分，看起来有点乱，可以参看下图说明更正一下。

更正 front-matter

本地调试

安装 Elog

Elog，一个开放式跨端博客解决方案，可以随意组合写作平台（语雀/Notion/FlowUs）和博客平台（Hexo/Vitepress/Confluence/WordPress）等，是本次实现语雀云端写作的关键。

本着非必要不升级的原则，我使用的 Node.js 一直以来都是 v12.14.0，本次安装使用的 Elog 要求至少 14 版本的 Node.js，故而我升级 Node.js 到最新的 LTS 版本，即 18 版本。至于如何升级，如果是 Windows，就卸载然后安装，如果是 Linux，推荐使用 NVM 安装。

全局安装 @elog/cli：

1
npm install -g @elog/cli

进入<博客构建目录>，执行以下命令进行初始化，会在根目录生成一份配置文件 elog.config.js 和本地调试用的环境变量文件 .elog.env。

1
elog init

将 .elog.env 加入 .gitignore，防止隐私数据提交：

1
2
3
4
5
6
7
8
.DS_Store
Thumbs.db
db.json
*.log
public/
node_modules/
.deploy*/
+.elog.env

配置

编辑 .elog.env，配置语雀认证的环境变量：

1
2
3
4
5
6
7
# 语雀（Token方式）
YUQUE_TOKEN=
# 语雀（帐号密码方式）
YUQUE_USERNAME=
YUQUE_PASSWORD=
YUQUE_LOGIN=
YUQUE_REPO=

Token 方式和帐号密码方式二选一，现在使用 Token 需要开会员，没有会员的就使用帐号密码方式。YUQUE_LOGIN 和 YUQUE_REPO 的获取方式见 elog 官方文档的关键信息获取。

再配置图床认证的环境变量，平台可在腾讯云、阿里云、又拍云、七牛云和 GitHub 中选择一个，详细配置方式见 elog 官方文档的关键信息获取。

编辑 elog.config.js，设置写作平台为 yuque-pwd（即帐号密码方式认证的语雀）：

1
2
3
4
5
...
write: {
-     platform: "yuque"
+    platform: "yuque-pwd",
...

配置本地部署方式：

1
2
3
4
5
6
7
8
9
10
11
12
13
...
deploy: {
    platform: "local",
    local: {
-      outputDir: "./docs",
+      outputDir: "source/_posts",
      filename: "title",
-      format: "markdown",
+      format: "matter-markdown",
      catalog: false,
      formatExt: "",
    },
...

开启图床，设置图床平台为腾讯云、阿里云、又拍云、七牛云或 GitHub：

1
2
3
4
5
6
7
...
image: {
-    enable: false,
+    enable: true
-    platform: "local",
+    platform: "<图床平台>",
...

最后配置图床，配置方式见 elog 官方文档的配置详情。

同步

1
elog sync -e .elog.env

如果日志显示同步成功，本地调试即成功。同时，注意到当前目录生成了一个缓存文件 elog.cache.json，其中是我们文章的原始数据。

持续集成

本地安装 @elog/cli：

1
npm install @elog/cli

为了防止 hexo 在生成博客源文件时报错，新建目录 cache，将 elog.cache.json 移动过去。

编辑 package.json，新建一个 NPM 命令用于同步：

1
2
3
4
5
6
7
8
9
...
"scripts": {
    "build": "hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server",
+    "sync": "elog sync -a cache/elog.cache.json"
  },
...

前往博客构建仓库添加密钥，如下图，添加 YUQUE_TOKEN(YUQUE_USERNAME、YUQUE_PASSWORD)、YUQUE_LOGIN、YUQUE_REPO 的值，再添加图床的密钥，如使用腾讯云作为图床平台，需添加 COS_SECRET_ID、COS_SECRET_KEY、COS_BUCKET、COS_REGION 和 COS_HOST 的值。

添加密钥

编辑 GitHub Actions 工作流：

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
name: hexo-build
# 仓库分支main有推送时执行jobs下定义的任务
on:
  push:
    branches:
      - main
# 设置时区为上海
env:
  TZ: Asia/Shanghai
jobs:
  # 定义名为blog-build的任务
  blog-build:
    # 定义运行的操作系统
    runs-on: ubuntu-latest
    # 定义步骤
    steps:
      # 签出仓库的默认分支，此处即为main，同时迁出子项目，此处即为主题仓库
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
       # 安装别名为lts/Hydrogen的Node.js，即18版本，同时进行全局缓存
-      - name: Install Node.js v12.14.0
+      - name: Install Node.js lts/Hydrogen
        uses: actions/setup-node@v3
        with:
-          node-version: "12.14.0"
+          node-version: "lts/Hydrogen"
          cache: "npm"
      # 缓存文件夹node_modules并生成唯一码
      - name: Cache dependencies
        uses: actions/cache@v3
        id: cache-dependencies
        with:
          path: node_modules
          key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}
      # 如果唯一码比对不成功，重新安装依赖，成功则沿用缓存
      - name: Install dependencies
        if: steps.cache-dependencies.outputs.cache-hit != 'true'
        run: npm ci
+      - name: Pull posts from Yuque
+        env:
+          YUQUE_TOKEN: ${{ secrets.YUQUE_TOKEN }}
+          YUQUE_LOGIN: ${{ secrets.YUQUE_LOGIN }}
+          YUQUE_REPO: ${{ secrets.YUQUE_REPO }}
+          COS_SECRET_ID: ${{ secrets.COS_SECRET_ID }}
+          COS_SECRET_KEY: ${{ secrets.COS_SECRET_KEY }}
+          COS_BUCKET: ${{ secrets.COS_BUCKET }}
+          COS_REGION: ${{ secrets.COS_REGION }}
+          COS_HOST: ${{ secrets.COS_HOST }}
+        run: |
+          # elog.cache.json被指定在子目录cache下，需要先创建，先判断有没有，没有才创建
+          [ ! -d "cache" ] && mkdir cache
+          npm run sync
      - name: Setup private rsa key
        env:
          DEPLOY_KEY: ${{secrets.DEPLOY_KEY}}
        run: |
          mkdir -p ~/.ssh/
          echo "$DEPLOY_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          ssh-keyscan gitee.com >> ~/.ssh/known_hosts
      - name: Download and clone PUBLIC
        run: |
          # 下载自己的GitHub用户仓库，下载的文件为master.zip
          curl -LsO https://github.com/ql-isaac/<自己的Github用户名>.github.io/archive/refs/heads/master.zip
          # 解压
          unzip master.zip -d .
          # 重命名为public
          mv <自己的Github用户名>.github.io-master/ public
          # 克隆自己的GitHub用户仓库，重命令为.deploy_git
          git clone git@github.com:ql-isaac/<自己的Github用户名>.github.io.git .deploy_git
      - name: Download DB
        uses: dawidd6/action-download-artifact@v2
        continue-on-error: true # 构件最多只能保存90天，90天过后这一步会报错，设置成报错继续执行
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          name: "DB"
      - name: Generate and deploy
        run: |
          git config --global user.name "${{secrets.GIT_NAME}}"
          git config --global user.email "${{secrets.GIT_EMAIL}}"
          npm run build && npm run deploy
      - name: Upload DB for next workflow to download
        uses: actions/upload-artifact@v3
        with:
          name: "DB"
          path: db.json
          retention-days: 90
+      - name: Upload Cache for next workflow to download
+        uses: actions/upload-artifact@v3
+        with:
+          name: "Cache"
+          path: cache
+          retention-days: 90
+      - name: Upload Posts for next workflow to download
+        uses: actions/upload-artifact@v3
+        with:
+          name: "Posts"
+          path: "source/_posts"
+          retention-days: 90
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
name: hexo-build
on:
  push:
    branches:
      - main
env:
  TZ: Asia/Shanghai
jobs:
  blog-build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
-      - name: Install Node.js v12.14.0
+      - name: Install Node.js lts/Hydrogen
        uses: actions/setup-node@v3
        with:
-          node-version: "12.14.0"
+          node-version: "lts/Hydrogen"
          cache: "npm"
      - name: Cache dependencies
        uses: actions/cache@v3
        id: cache-dependencies
        with:
          path: node_modules
          key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}
      - name: Install dependencies
        if: steps.cache-dependencies.outputs.cache-hit != 'true'
        run: npm ci
+      - name: Pull posts from Yuque
+        env:
+          YUQUE_TOKEN: ${{ secrets.YUQUE_TOKEN }}
+          YUQUE_LOGIN: ${{ secrets.YUQUE_LOGIN }}
+          YUQUE_REPO: ${{ secrets.YUQUE_REPO }}
+          COS_SECRET_ID: ${{ secrets.COS_SECRET_ID }}
+          COS_SECRET_KEY: ${{ secrets.COS_SECRET_KEY }}
+          COS_BUCKET: ${{ secrets.COS_BUCKET }}
+          COS_REGION: ${{ secrets.COS_REGION }}
+          COS_HOST: ${{ secrets.COS_HOST }}
+        run: |
+          [ ! -d "cache" ] && mkdir cache
+          npm run sync
      - name: Setup private rsa key
        env:
          DEPLOY_KEY: ${{secrets.DEPLOY_KEY}}
        run: |
          mkdir -p ~/.ssh/
          echo "$DEPLOY_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          ssh-keyscan gitee.com >> ~/.ssh/known_hosts
      - name: Download and clone PUBLIC
        run: |
          curl -LsO https://github.com/ql-isaac/<自己的Github用户名>.github.io/archive/refs/heads/master.zip
          unzip master.zip -d .
          mv <自己的Github用户名>.github.io-master/ public
          git clone git@github.com:ql-isaac/<自己的Github用户名>.github.io.git .deploy_git
      - name: Download DB
        uses: dawidd6/action-download-artifact@v2
        continue-on-error: true
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          name: "DB"
      - name: Generate and deploy
        run: |
          git config --global user.name "${{secrets.GIT_NAME}}"
          git config --global user.email "${{secrets.GIT_EMAIL}}"
          npm run build && npm run deploy
      - name: Upload DB for next workflow to download
        uses: actions/upload-artifact@v3
        with:
          name: "DB"
          path: db.json
          retention-days: 90
+      - name: Upload Cache for next workflow to use
+        uses: actions/upload-artifact@v3
+        with:
+          name: "Cache"
+          path: cache
+          retention-days: 90
+      - name: Upload Posts for next workflow to use
+        uses: actions/upload-artifact@v3
+        with:
+          name: "Posts"
+          path: "source/_posts"
+          retention-days: 90

提交并推送：

1
2
3
git add .
git commit -m ":green_heart: 使用elog实现语雀云端写作"
git push

再次编辑 GitHub Actions 工作流：

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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
name: hexo-build
on:
# 将执行jobs下定义的任务的充分条件改为有类型为publish的外部事件触发
-  push:
-    branches:
-      - main
+  repository_dispatch:
+    types:
+      - publish
# 设置时区为上海
env:
  TZ: Asia/Shanghai
jobs:
  # 定义名为blog-build的任务
  blog-build:
    # 定义运行的操作系统
    runs-on: ubuntu-latest
    # 定义步骤
    steps:
      # 签出仓库的默认分支，此处即为main，同时迁出子项目，此处即为主题仓库
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
      # 安装别名为lts/Hydrogen的Node.js，即18版本，同时进行全局缓存
      - name: Install Node.js lts/Hydrogen
        uses: actions/setup-node@v3
        with:
          node-version: "lts/Hydrogen"
          cache: "npm"
      # 缓存文件夹node_modules并生成唯一码
      - name: Cache dependencies
        uses: actions/cache@v3
        id: cache-dependencies
        with:
          path: node_modules
          key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}
      # 如果唯一码比对不成功，重新安装依赖，成功则沿用缓存
      - name: Install dependencies
        if: steps.cache-dependencies.outputs.cache-hit != 'true'
        run: npm ci
+      - name: Download Posts from the last workflow
+        uses: dawidd6/action-download-artifact@v2
+        continue-on-error: true # 构件最多只能保存90天，90天过后这一步会报错，设置成报错继续执行
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          name: "Posts"
+          path: "source/_posts"
+      - name: Download Cache from the last workflow
+        continue-on-error: true
+        uses: dawidd6/action-download-artifact@v2
+        continue-on-error: true
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          name: "Cache"
+          path: "cache"
      - name: Pull posts from Yuque
        env:
          YUQUE_TOKEN: ${{ secrets.YUQUE_TOKEN }}
          YUQUE_LOGIN: ${{ secrets.YUQUE_LOGIN }}
          YUQUE_REPO: ${{ secrets.YUQUE_REPO }}
          COS_SECRET_ID: ${{ secrets.COS_SECRET_ID }}
          COS_SECRET_KEY: ${{ secrets.COS_SECRET_KEY }}
          COS_BUCKET: ${{ secrets.COS_BUCKET }}
          COS_REGION: ${{ secrets.COS_REGION }}
          COS_HOST: ${{ secrets.COS_HOST }}
        run: |
          [ ! -d "cache" ] && mkdir cache
          npm run sync
      - name: Setup private rsa key
        env:
          DEPLOY_KEY: ${{secrets.DEPLOY_KEY}}
        run: |
          mkdir -p ~/.ssh/
          echo "$DEPLOY_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          ssh-keyscan gitee.com >> ~/.ssh/known_hosts
      - name: Download and clone PUBLIC
        run: |
          # 下载自己的GitHub用户仓库，下载的文件为master.zip
          curl -LsO https://github.com/ql-isaac/<自己的Github用户名>.github.io/archive/refs/heads/master.zip
          # 解压
          unzip master.zip -d .
          # 重命名为public
          mv <自己的Github用户名>.github.io-master/ public
          # 克隆自己的GitHub用户仓库，重命令为.deploy_git
          git clone git@github.com:ql-isaac/<自己的Github用户名>.github.io.git .deploy_git
      - name: Download DB
        uses: dawidd6/action-download-artifact@v2
        continue-on-error: true # 构件最多只能保存90天，90天过后这一步会报错，设置成报错继续执行
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          name: "DB"
      - name: Generate and deploy
        run: |
          git config --global user.name "${{secrets.GIT_NAME}}"
          git config --global user.email "${{secrets.GIT_EMAIL}}"
          npm run build && npm run deploy
      - name: Upload DB for next workflow to download
        uses: actions/upload-artifact@v3
        with:
          name: "DB"
          path: db.json
          retention-days: 90
      - name: Upload Cache for next workflow to download
        uses: actions/upload-artifact@v3
        with:
          name: "Cache"
          path: cache
          retention-days: 90
      - name: Upload Posts for next workflow to download
        uses: actions/upload-artifact@v3
        with:
          name: "Posts"
          path: "source/_posts"
          retention-days: 90
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
name: hexo-build
on:
-  push:
-    branches:
-      - main
+  repository_dispatch:
+    types:
+      - publish
env:
  TZ: Asia/Shanghai
jobs:
  blog-build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
      - name: Install Node.js lts/Hydrogen
        uses: actions/setup-node@v3
        with:
          node-version: "lts/Hydrogen"
          cache: "npm"
      - name: Cache dependencies
        uses: actions/cache@v3
        id: cache-dependencies
        with:
          path: node_modules
          key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}
      - name: Install dependencies
        if: steps.cache-dependencies.outputs.cache-hit != 'true'
        run: npm ci
+      - name: Download Posts from the last workflow
+        uses: dawidd6/action-download-artifact@v2
+        continue-on-error: true
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          name: "Posts"
+          path: "source/_posts"
+      - name: Download Cache from the last workflow
+        uses: dawidd6/action-download-artifact@v2
+        continue-on-error: true
+        with:
+          github_token: ${{secrets.GITHUB_TOKEN}}
+          name: "Cache"
+          path: "cache"
      - name: Pull posts from Yuque
        env:
          YUQUE_TOKEN: ${{ secrets.YUQUE_TOKEN }}
          YUQUE_LOGIN: ${{ secrets.YUQUE_LOGIN }}
          YUQUE_REPO: ${{ secrets.YUQUE_REPO }}
          COS_SECRET_ID: ${{ secrets.COS_SECRET_ID }}
          COS_SECRET_KEY: ${{ secrets.COS_SECRET_KEY }}
          COS_BUCKET: ${{ secrets.COS_BUCKET }}
          COS_REGION: ${{ secrets.COS_REGION }}
          COS_HOST: ${{ secrets.COS_HOST }}
        run: |
          [ ! -d "cache" ] && mkdir cache
          npm run sync
      - name: Setup private rsa key
        env:
          DEPLOY_KEY: ${{secrets.DEPLOY_KEY}}
        run: |
          mkdir -p ~/.ssh/
          echo "$DEPLOY_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          ssh-keyscan gitee.com >> ~/.ssh/known_hosts
      - name: Download and clone PUBLIC
        run: |
          curl -LsO https://github.com/ql-isaac/<自己的Github用户名>.github.io/archive/refs/heads/master.zip
          unzip master.zip -d .
          mv <自己的Github用户名>.github.io-master/ public
          git clone git@github.com:ql-isaac/<自己的Github用户名>.github.io.git .deploy_git
      - name: Download DB
        uses: dawidd6/action-download-artifact@v2
        continue-on-error: true
        with:
          github_token: ${{secrets.GITHUB_TOKEN}}
          name: "DB"
      - name: Generate and deploy
        run: |
          git config --global user.name "${{secrets.GIT_NAME}}"
          git config --global user.email "${{secrets.GIT_EMAIL}}"
          npm run build && npm run deploy
      - name: Upload DB for next workflow to download
        uses: actions/upload-artifact@v3
        with:
          name: "DB"
          path: db.json
          retention-days: 90
      - name: Upload Cache for next workflow to download
        uses: actions/upload-artifact@v3
        with:
          name: "Cache"
          path: cache
          retention-days: 90
      - name: Upload Posts for next workflow to download
        uses: actions/upload-artifact@v3
        with:
          name: "Posts"
          path: "source/_posts"
          retention-days: 90

将 source 下 _posts 和 cache 下的 elog.cache.json 加入 .gitignore 并删除掉，这两个地方的文件已经不需要。

最终提交并推送：

1
2
3
git add .
git commit -m ":green_heart: 使用elog实现语雀云端写作（终）"
git push

这样，在语雀上写好博文并更新，只需要地址栏输入以下地址（外部事件触发 API），即可触发持续集成，实现云端写作。

1
https://serverless-api-elog.vercel.app/api/github?user=<自己GitHub用户名>&repo=<博客构建仓库名>&event_type=publish&token=<自己生成的Token>

生成 Token 的方式（勾选 repo 的权限）：

image.png

以上 API 是 elog 官方在 Vercel 上搭建的，使用的 Vercel 默认域名，会经常被墙，我们可以自己搭建一个并且使用上自己的域名（未备案也行，因为 Vercel 是国外服务）。

fork serverless-api，登录 Vercel，新建，导入刚刚 fork 的项目，部署。到域名设置那里，添加自己的域名，如 publish.xxx.xx，再到域名供应商那里添加一下 cname 解析，最后回到域名设置那里，确认解析生效，这样，将以上地址中域名替换为自己的域名得到自己的 API。