博客迁移到Hexo

逐渐意识到自己需要的只是简单的功能，像Halo、WordPress这些重量级功能强大的工具并不是我所想要的。
打算从Halo换到Hexo之后白嫖GitHub Pages。

环境和准备

Hexo可以理解成一个markdown静态页面生成器，集成各种插件和主题，让生成的静态页面更加好看和功能强大。
我这里是将markdown源文件和生成的文件分开了2个仓库，如果放一起的话会简单不少。

GitHub Pages 源仓库配置

GitHub Pages读取的默认是用户 username.github.io 这个仓库，先创建这个仓库，加个README文件就行，主要是默认生成main分支免去再次创建分支的麻烦。

这个仓库就是用于发布Hexo生成的静态页面的仓库，也是GitHub Pages的源仓库。然后在这个仓库 Settings - Pages 中配置 Source 来自于 main 分支的根文件夹。

然后本机生成ssh key密钥对，将公钥配置到 Settings - Deploy keys ，名称就叫 HEXO_DEPLOY_KEY 。

Hexo源仓库配置

创建一个私有仓库，用于存储Hexo配置和markdown源文件，在 Settings - Secrets And variables - Actions 创建一个名为 HEXO_DEPLOY_KEY 的 Secret ，内容就是上面生成的私钥。GitHub Actions就是在这个仓库运行，推送静态文件到上面的仓库。

本机环境配置

• Node.js 建议12及以上
• Git

迁移

从Halo导出markdown源文件

由于新版本的Halo备份是没有markdown格式的，所以只能依靠官方插件市场的 halo-plugin-export-md 来导出markdown文件，同时该插件还支持填充元数据，Hexo也是依赖这些元数据来处理文章的。

注意该源码导出的markdown date 日期是Halo里文章的创建日期，如果需要的是文章的发布日期，就需要自己fork修改了。
源码在 #195 ，注意里面很多没有空判断，导致导出的元数据中很多空值，在Hexo生成静态文件时会报错，所以这里最好还是自己fork修改一份进行导出。

本地配置Hexo

安装Hexo非常简单，按照 官方文档 可以很快上手。

Hexo工作目录下 _config.yml 配置参考 官方文档 即可轻松配置。

source

source 文件夹是默认的存储文章markdown源文件的地方，可以在 _config.yml 中自定义。

该文件夹下 _posts 存储的是发布的文章源文件，_drafts 存储的是草稿。

scaffolds

工作目录下的 scaffolds 文件夹存储的是模板文件，默认有 page.md post.md draft.md ，你可以自定义模板格式，然后就可以使用 hexo new page|post|draft xxx 来生成对应的markdown文件了。生成的文件都在上面的源文件夹下。

注意页面的生成有点不一样，hexo new page xxx 在source文件夹生成了 source/page/index.md ，也就是说页面文件都是这样的读取方式，哪怕手动创建页面也要按照这样的格式。

themes

主题文件夹，一般主题都是引用的别的开源项目，这里最好使用 git submodule 的方式来引用。

1

git submodule add url themes/xxx

上面_config.yml 配置的主题就是这个 xxx 文件夹名称，同时主题的配置最好使用 _config.xxx.yml 这种格式，放在工作根目录，防止污染主题文件夹。

scripts

这个是脚本文件夹，Hexo从这里加载js脚本。比如主题没有提供注入功能，就可以简单的注入脚本和css。其他的可以参考 这里

简单的操作都可以通过这里的脚本执行。

使用 hexo clean && hexo g && hexo s 就可以本地预览了，没问题就把上面的代码推送到创建的私有仓库中。

配置GitHub Actions

安装部署插件

1

npm install hexo-deployer-git

注意这个插件配置的时候不要使用token，很难用，项目README写的不清楚，折腾半天都没搞定。
url使用 git@github.com:xxx/xxx.git ssh验证。

配置文件

在Hexo工作目录创建 .github/workflows/pages.yml ：

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

name: Pages  
  
on:  
  push:  
    branches:  
      - main # default branch  
  
jobs:  
  build:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: actions/checkout@v4  
        with:  
          token: ${{ secrets.GITHUB_TOKEN }}  
          # If your repository depends on submodule, please see: https://github.com/actions/checkout  
          submodules: true  
      - name: Use Node.js 23  
        uses: actions/setup-node@v4  
        with:  
          # Examples: 20, 18.19, >=16.20.2, lts/Iron, lts/Hydrogen, *, latest, current, node  
          # Ref: https://github.com/actions/setup-node#supported-version-syntax          node-version: "23"  
      - name: Cache NPM dependencies  
        uses: actions/cache@v4  
        with:  
          path: node_modules  
          key: ${{ runner.OS }}-npm-cache  
          restore-keys: |  
            ${{ runner.OS }}-npm-cache  
      - name: Install Dependencies  
        run: npm install  
      - name: Build  
        run: npm run build  
      - name: Install Hexo CLI  
        run: npm install -g hexo-cli  
      - name: Deploy hexo  
        env:  
          HEXO_DEPLOY_KEY: ${{ secrets.HEXO_DEPLOY_KEY }}  
        run: |  
          mkdir -p ~/.ssh  
          echo "$HEXO_DEPLOY_KEY" > ~/.ssh/id_rsa  
          chmod 600 ~/.ssh/id_rsa  
          ssh-keyscan github.com >> ~/.ssh/known_hosts  
          git config --global user.name "username"  
          git config --global user.email "email"  
          hexo d -m "${{ github.event.head_commit.message }}"

主要是最后一步的ssh配置，读取的key就是上面配置在私有仓库的key，其他的按照自己的配置即可。

submodules: true 构建时自动拉取子模块的代码。

推送配置文件之后即可自动触发构建，GitHub Pages公开仓库也会有个默认的构建。

推送私有仓库时候如果不想触发构建，可以在提交信息添加 [skip actions] 来跳过，可以参考 官方文档 。

后续和优化

压缩

使用的是 hexo-yam

压缩酌情选择开启，常见的 html css js svg 都是建议压缩的，能减少不少体积。

sitemap

使用的是 hexo-generator-sitemap

主题子模块

如果用的主题是自己维护的，在push了对主题的修改之后，Hexo根目录所在的私有仓库会有个 themes/xxx 的文件夹修改，如果你需要主题的修改生效的话需要提交这个文件夹的修改。
其实就是记录的是当前文件夹引用的是哪个版本的子模块，如果不提交就永远使用的旧主题版本。
同样如果是别人的开源主题，想要使用新版本，也需要更新子模块，提交这个文件夹的更新。

CNAME

由于插件 hexo-deployer-git 每次推送都是清空了分支的，所以配置 CNAME 就不能从仓库那里配置了，在markdown源文件夹根目录下创建即可。

本站所有文章除特别声明外，均采用 BY-NC-SA 4.0 许可协议。转载请注明出处！