重新部署Hexo的踩坑记

其实 hexo 本身倒是没有什么坑？不过这次按照朋友的推荐上了 GitHub 的 CI，因为自己粗心大意所以还是有点磕磕碰碰。就把中间遇到的一些问题和解决方案写一下吧。

1. 首先需要准备一对密钥，私钥存在仓库的设置里面的 Secret > Actions Secrets 里，我这里叫做 HEXO_DEPLOY_PRIVATE。

   然后在 CI 脚本里面对应部署 Hexo 的地方，加一行

   env:
     ACTION_DEPLOY_KEY: ${{ secrets.HEXO_DEPLOY_PRIVATE }}

   这里有一点需要注意的是私钥复制过去的时候要把 BEGIN 和 END 那两行也复制过去。我忘记复制了结果提示格式错误（

   至于公钥的话，也是在仓库的设置里，Deploy keys 里面添加即可，需要添加 Write 权限。

2. Workflow 的流程会使用到两个分支，main 分支里什么都不要动，然后所有的改变都在另一个分支（姑且称为 hexo）里面进行。不同于直接在命令行里面 hexo d，这里每次提交的都是整个 hexo 文件夹，也就是说包括了 scaffolds，source，themes 这些文件夹（当然也有 node_modules 和 public，不过它们会被 git ignore 掉）。这样的话，网站本身是通过 CI 从 hexo 分支生成然后分发到 main 分支的。

   对应的，CI 脚本应该放在 hexo 分支里面，因为每次一个分支发生变动的时候只会调用这个分支里面的 CI action。文件夹应该是 github/workflows，文件名随意（yml格式结尾）。所以结论是只要把CI脚本也放在 hexo 文件夹下对应的路径就好了。

3. 已经有了仓库的情况下，还需要在仓库设置里的 Pages 下把 branch 改为 main，路径为 /(root)，这样才能开启 GitHub Pages 的功能。

4. 自定义域名如果要用根域名的话，要设置 apex 域，需要在自己的 DNS 运营商那边把 @ 的 A 记录改为 GitHub 的 IP。不能用 CNAME 的方式使用根域名。

   具体关于域名绑定的操作步骤可以参考 GitHub 官网文档。

   官网文档上也提到了其他的一些注意事项，例如说不要用 wildcard (*)，不然所有人都可以在你的网站上托管一个站点，同样的，在不再使用 GitHub Pages 的时候，应该立即删除 DNS 记录以防止域名被接管。

5. 设置完 apex 域之后，还需要给 www 加一个 CNAME 的解析，这样 GitHub 那边才可以正确访问域名的 DNS。不然的话，就算加了 HTTPS 也会提示证书错误。

6. 从 Mac 推送的话，可能会遇到这个错误

   npm ERR! code EBADPLATFORM
   npm ERR! notsup Unsupported platform for fsevents@2.3.2: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})

   原因在于在 Mac 上 npm 会下载一个叫 fsevents 的依赖。按理来说这个依赖是 optional 的，但是 npm install --no-optional 也不管用。如果在所有 npm 指令前面，加上一行 npm config set ignore-optional true，就好了。

   8月5日更新：在另一个项目里又遇到了fsevents的问题，这次明明加了那一行还是不行。索性直接把fsevents从依赖里删掉了。然后就可以了（

7. 因为是通过 deployer 推送的，会覆盖掉仓库里的 CNAME 文件。所以我们还要在本地的 /source 文件夹下添加一个 CNAME文件。文件格式方面的要求可以看这里。

8. 然后就好了（似乎？

9. 在使用了mathjax的情况下又出现了新的问题：按照教程需要卸载hexo-renderer-marked安装hexo-renderer-pandoc，然后在渲染的时候就出错了：

   err: Error: 
   Error: R][hexo-renderer-pandoc] On undefined
   Error: R][hexo-renderer-pandoc] pandoc exited with code null.

   确切的说在本地渲染没有问题，但是在GitHub action上出错了。

   按照这里的说法，是因为没有安装pandoc，于是修改deploy.yml:

   • 在job里面增加环境变量：

     env: 
         RUNNER_TOOL_CACHE: /opt/hostedtoolcache

   • 在step里面安装pandoc：

     - name: Install Pandoc
         run: |
          curl -s -L https://github.com/jgm/pandoc/releases/download/2.9.2/pandoc-2.9.2-linux-amd64.tar.gz | tar xvzf - -C $RUNNER_TOOL_CACHE/

   • 在每一处调用hexo的地方（setup hexo和hexo deploy）更新环境变量：

     export PATH="$PATH:$RUNNER_TOOL_CACHE/pandoc-2.9.2/bin"

   这样的话就ok了，不过GitHub action确实很不好用，出错的时候debug非常麻烦。