写在前面

---

暑假回来打算把自己的博客重新整理一下，一看才发现上一次电脑重装的时候没把博客的本地数据给存下来，这下好了，不得不重新搭建一遍了。正好之前的 Blog 采取的是本地文件+hexo 部署的手动方式，编写使用的 Typera，现在切换到 Obsidian 以后多了不少的实用工具，也一起更新一下。本以为只需要简单的再部署一遍就 OK 了，没想到踩了一堆的坑，正好一起记录一下。

本文的主要内容：
hexo 本地搭建
如何更换主题（以Haojen/hexo-theme-Claudia为例）
网站仓库搭建
hexo 线上部署
更换个人域名
源码仓库搭建
Github Action 的实现
obsidian 配置博客仓库

本项目基于 windows 平台，但大部分部署过程应该大同小异，可以参考使用。

更新日志

日期	主要内容
2023.07.01	修正部分错误
223.07.17	补充“迁移至新电脑”， 补充 git 安装教程，更新 github action 部分配置

整体思路

---

为了避免搭着搭着忘记自己在干啥了，先整理一下思路吧。

第一步当然是搭建 hexo 静态博客，静态也就意味着部署 deploy 时上传为一个处理后的静态网站，直接在这个网站源码中塞入 md 文件显然无法正常显示。hexo 采取的是本地搭建 + 本地编写 + 线上部署的方式，也就是说，后续会涉及到两个主要的代码仓库：源码仓库与页面仓库，一般的实现方式为源码本地存储，页面仓库使用 GithubPage 实现，在这里我们将源码也上传到了个人的私有仓库中，一方面可以实现博客文章的线上存储，另一方面也方便我们在其他电脑上重新搭建我们的博客环境。

那么问题随之而来，我们原先搭建好的博客可以在本地通过hexo g & hexo d完成部署，那么此时是否意味着我们每次还需要多执行一次git commit push来完成源码的存储呢？实际上并不需要，我们可以通过 github action 来实现每次上传源码仓库的同时，自动通过一个“虚拟机”来完成 hexo 的部署工作，换而言之，更新前的工作流如下：

• hexo n 创建新文章 –> 完成文章编写 –> hexo g & hexo d
  更新后的工作流如下:
• hexo n 创建新文章 –> 完成文章编写 –> git add & commit & push

那么在此基础上, 如何使用 obsidian 来管理博文的创建、编写和部署呢？这里使用了模板和 git 插件等，最后形成的工作流就是以下：

• obsidian 模板创建新文章 –> 完成文章编写 –> obsidian 中commit & push

参考资料

---

本文主要参考了以下博客，一些其他的 issue 之类可能有所遗漏：

使用 github 与 hexo 完成网站搭建的教程相当多，仅给出一个参考：
GitHub+Hexo 搭建个人网站详细教程 - 知乎 (zhihu.com)
采用的主题如下:
Haojen/hexo-theme-Claudia: 📌 Concisely designed & easy to config, match device dark mode, 90+ Lighthouse scoring (github.com)
官方文档, 包含基础的操作和编写格式:
文档 | Hexo
Obsidian 与 hexo 配合相关:
Hexo + Obsidian + Git 完美的博客部署与编辑方案 | EsunR-Blog

全自动部署核心部分，评论区提供了不少问题的解决方案：
使用 Github Action 实现全自动部署 | Akilar の糖果屋

域名购买, 我买的阿里云的, 其他应该也大同小异:
阿里云-为了无法计算的价值

hexo 本地部署

---

基础配置安装

nodeJs

需要安装以下内容:
nodeJs: 用于安装 hexo 和其他插件, 注意安装完成后需要配置环境变量
Download | Node.js
node -v 和npm -v 检查是否安装成功

在继续之前, 如果你已经大致了解创建 github 仓库的步骤, 可以选择跳转至源码仓库搭建部分, 先完成仓库的建立, 后在仓库路径中完成 hexo 的搭建.

hexo

然后在电脑中创建一个文件夹作为 Blog 的本地存储位置, 例如 Blog, 随后在文件夹内右键使用 cmd:

使用 npm 命令安装 Hexo，输入：

npm install -g hexo-cli

安装完成后，初始化我们的博客，输入：

hexo init blog

注意，这里的命令都是作用在刚刚创建的 Blog 文件夹中。

为了检测我们的网站，分别按顺序输入以下命令：

hexo new {test post title}

hexo g

hexo s

这些命令在附录中有介绍，完成后，打开浏览器输入地址：

localhost:4000

就可以看出我们的博客网站啦(理论上是 Hello World)

git

后续我们会使用 git 完成线上仓库和部署的相关操作，如果还没有安装 git 的话需要安装一下。

参考以下文章完成Git - 安装 Git (git-scm.com)（可以选择一路默认配置下来，也可以调整一下安装路径。

完成安装后在任意路径文件夹下右键便可看到git bash here, 点击进入命令行界面。

如果是第一次使用 git， 将以下代码中"Your Name"与"email@example.com"替换为自己的用户名（与 github 保持一致）与邮箱（与 github 账户保持一致）后复制黏贴进命令行完成设置。

git config --global user.name "Your Name"
git config --global user.email "email@example.com"

如果在后续的任何 git 环节遇到了问题, 或者想深入了解一下 git(毕竟挺有用的不是吗?), 可以参考Git 教程 - 廖雪峰的官方网站 (liaoxuefeng.com)或者直接 Bing/google，你的问题大概率已经有人遇到并解决了。

配置 ssh key

git 使用 SSH 配置，配置后才能与 github 相连。
在 git bash 命令行中完成以下操作:

ssh-keygen -t rsa -C "email@example.com"
cd ~/.ssh
cat id_rsa.pub

此时命令行应当返回 ssh-rsa 开头的字符串, 将其复制到 github 的You-Settings-SSH and GPG Keys--New SSH Key中, name 字段填写自己名字就行。

更换主题

---

主题相当于预先编写好的网站美化, 比较出名的包含 Next, Butterfly 等, 这里介绍使用 Claudia 的具体方法, 以下内容主要基于hexo-theme-Claudia/README-CN.md at master · Haojen/hexo-theme-Claudia · GitHub

进入 themes 文件夹，从 github 上 clone 主题

git clone https://github.com/Haojen/hexo-theme-Claudia.git

注意! clone 结束后记得将主题从 git 的暂存区中删除, 不然后续上传源码仓库会报错!

# 删除hexo-theme-Claudia下.git文件夹
rm themes/hexo-theme-Claudia/.git

# 这里直接删除了暂存区文件
rm .git/index

根目录下完成插件安装:

#必要
npm install hexo-renderer-pug
npm install hexo-renderer-sass
npm install hexo-generator-search

#选择性安装
# 如果需要添加订阅功能
npm install hexo-generator-feed
# 流程图功能
npm install hexo-filter-flowchart --save
# Emoji
npm install hexo-filter-github-emojis --save
# 搜索功能
npm install hexo-generator-search --save
# 数学公式
npm install hexo-renderer-mathjax --save

其他的配置可以参考hexo-theme-Claudia-CN自行实现, 完成配置后进入 hexo 配置文件_config.yml, 修改 theme 内容:

# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
theme: hexo-theme-Claudia

注意, 此处的填写的名称为 themes 文件夹中对应主题文件夹的名称.

完成以上步骤后依次执行hexo g, hexo s查看是否成功使用主题, 如果失败可以尝试执行hexo clean后再次尝试运行.

到此为止, 我们已经在本地完成了基本的网站搭建工作, 接下来就是把他搬上线啦

网站仓库搭建

---

在 github 中新建一个公开的, 名称为{your-blog}.github.io的仓库, 这个仓库用来存放我们部署的静态网页, 目前 github 默认的分支为 main 分支, 我们直接使用 main 分支进行部署. 在当前的 github 版本中, github Page 会自动启用, 我们在此部分不再关心.

在本地_config.yml中修改 deploy 的目标和 url 地址, 我们部署的时候会将产生的静态文件写入

# URL
## Set your site url here. For example, if you use GitHub Page, set url as 'https://username.github.io/project'
url: https://{username}.github.io/{your-blog}.github.io

# Deployment
## Docs: https://hexo.io/docs/one-command-deployment
deploy:
  type: 'git'
  repo: git@github.com:{username}/{your-blog}.github.io.git
  branch: main

保存后回到 cmd 中, 执行hexo g & hexo d, 执行完成后查看仓库中是否有新的提交, 随后访问https://{username}.github.io/{your-blog}.github.io, 理论上你已经可以在互联网中查看到你的网页了!

如果访问出现 404 或其他问题, 尝试访问{your-blog}.github.io仓库的Settings-Pages, 查看 github Page 是否正确启用, 以及查看网址是否正确.

如果你之前配置过其他博客站点, 他们可能会占用你希望访问的网址(特别是需要使用以前是用的域名时), 将其他占用仓库的 githubPage 取消自定义域名, 或者直接停用或转为 private, 然后刷新{your-blog}.github.io仓库通常可以解决问题.

_config.yml 中的 url 地址请以{your-blog}.github.io仓库的Settings-Pages中提供的为准.

使用你的域名

访问{your-blog}.github.io仓库的Settings-Pages, 你可能注意到你可以为自己的网页选择自己的域名,这显然比让其他人打一大串 github.io 要方便多了.

首先, 选择一个域名平台购买一个自己喜欢的域名, 通常 com 域名更为通用, 当然价格也更贵, cn 和 top 使用的多一些, 价格也更实惠. 以下以阿里云为例, 阿里云-为了无法计算的价值, 遇到问题可以参考以下博客: hexo 绑定域名 - 知乎 (zhihu.com)

完成域名的购买, 这一环节的主要困难为钱包的问题.

随后进入域名控制台, 对自己的域名进行解析, 在此处需要添加以下记录:

主机记录	记录类型	记录值
@	A	185.199.109.153
@	A	185.199.110.153
@	A	185.199.111.153
@	A	185.199.109.153
www	CNAME	{your-blog}.github.io

然后回到{your-blog}.github.io仓库的Settings-Pages, 在 Custom domain 中填写你的域名www.xxxx.xxx, github Page 会自动完成 CNAME 的创建, 如果勾选 Enforce HTTPS, github 会自动完成 SSL 证书的签发.

如果出现主题未能成功加载(也就是只包含了 html 内容), 可以尝试将_confg.yml 中的 url 修改为自己的域名, 或再次检查 url 是否填写错误.

源码仓库搭建

在之前的环节里, 我们的 hexo 源码都只存放在了本地, 接下来我们希望把源码也上传 github 维护.

创建一个新的私有仓库{blogRepo}, 在本地根目录下执行以下命令:

# 新建git
git init

# 建立提交
git add .
git commit -m "repo init"
git remote add origin {your Reposory Url}
git push -u origin main

如果出现报错信息指向 themes 文件夹，考虑在安装主题的时候是否未将主题从暂存区中删除。
如果出现其他 git 仓库方面的问题，互联网检索是个更优的选择。

Github Action 的实现

接下来我们就要实现 github action， 它可以将持续性的完成网页的自动部署。这一部分主要参考了博客：使用 Github Action 实现全自动部署 | Akilar の糖果屋

首先，前往 github 个人Settings -- Developers Settings -- Personnal access token, 选择 classic 类型Generate new Token, 将该 Token 的expiration date设置为 none, 此时记得将 Token 复制出来!, 可以新建一个如下的 txt 文档记录:

# 在记事本中逐个记录

# 本地地址
[Blogroot]：D:\Blog\{yourBlog}

#源码仓库
[SourceRepo]：{your name}/{blog-repo}

[SiteBlogRepo]
  [GITHUBBLOGREPO]：{your-blog}.github.io

[SiteUsername]
  [GITHUBUSERNAME]：{your name}

[SiteToken]
  [GITHUBTOKEN]：{your token here}

[GITHUBEMAIL]：{your email}

再访问Settings -- Actions -- General, 将Actions permissions修改为Allow all, Workflow permissions修改为Read and write

回到源码仓库, 访问Settings -- Secrets and variables -- Newrepository secret, 将 GITHUBEMAIL, GITHUBBLOGREPO, GITHUBUSERNAME, GITHUBTOKEN 依次填写.

然后在源目录的.github文件夹下, 创建.github\workflows\autodeploy.yml文件, 编写一下信息,:

注意！需要提前本地查询node -v确定版本号, 本文档基于node 16.9.1编写

# 当有改动推送到master分支时，启动Action
name: 自动部署

on:
  push:
    branches:
      - main #2020年10月后github新建仓库默认分支改为main

  release:
    types:
      - published

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: 检查分支
      uses: actions/checkout@v3   #原v2支持至node12， 执行失败可尝试替换
      with:
        ref: main #2020年10月后github新建仓库默认分支改为main

    - name: 安装 Node
      uses: actions/setup-node@v3  #原v1支持至node12， 执行失败可尝试替换
      with:
        node-version: "16.9.1" #action使用的node版本，本地用node -v查询版本号。

    - name: 安装 Hexo
      run: |
        export TZ='Asia/Shanghai'
        npm install hexo-cli -g

    - name: 缓存 Hexo
      uses: actions/cache@v3  #原v1支持至node12， 执行失败可尝试替换
      id: cache
      with:
        path: node_modules
        key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}

    - name: 安装依赖
      if: steps.cache.outputs.cache-hit != 'true'
      run: |
        npm install --save

    - name: 生成静态文件
      run: |
        hexo clean
        hexo generate

    - name: 部署 #此处master:main 指从本地的master分支提交到远程仓库的main分支, 本地git的默认分支为master, 一般情况不需要修改
      run: |
        cd ./public
        git init
        git config --global user.name '${{ secrets.GITHUBUSERNAME }}'
        git config --global user.email '${{ secrets.GITHUBEMAIL }}'
        git add .
        git commit -m "${{ github.event.head_commit.message }} $(date +"%Z %Y-%m-%d %A %H:%M:%S") Updated By Github Actions"
        git push --force --quiet "https://${{ secrets.GITHUBUSERNAME }}:${{ secrets.GITHUBTOKEN }}@github.com/${{ secrets.GITHUBUSERNAME }}/${{ secrets.GITHUBBLOGREPO }}" master:main

随后将代码上传至仓库, 查看仓库的 Actions, 检查 workflows 是否正常工作, 点击最近一次的 workfows, 查看是否出现报错信息, 无报错信息则前往{your-blog}.github.io仓库检查 Actions 是否出发 deploy action, 如果执行成功则网页已成功通过 github Action 部署

如果源码仓库出现警告deploy: The process '/usr/bin/git' failed with exit code 128, 进一步点击查看 Post 检查分支中是否出现错误fatal: No url found for submodule path 'themes/hexo-theme-Claudia' in .gitmodules, 该错误说明 clone 结束后主题未从 git 的暂存区中删除, 删除后重试即可

此时, 由于我们的部署工作在 github 上完成, 本地的部分文件无需提交至仓库, 点击根目录下.gitignore,添加以下内容:

.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/
_multiconfig.yml

如果你很担心后续仓库的恢复会出现问题的话，也可以选择把所有内容都传上去，当然这样上传的速度就会慢一些了。

obsidian 配置博客仓库

obsidian 可以很方便的管理、编写本地的 md 文件, 本部分做了一些初步的整合和优化操作, 来让编写博客的过程更加丝滑, 可参考博客Hexo + Obsidian + Git 完美的博客部署与编辑方案 | EsunR-Blog

首先, 在 obsidian 中打开其他仓库, 打开我们的博客文件夹即可.

为了方便的完成博客的提交, 在第三方插件中下载Obsidian Git, 启用后即可使用Ctrl + p命令调用commit all changes和push操作, 当然, 我们也可以将命令进行集成, 比如Commander就可以进一步整合为一个命令.

显然, 通过 hexo n 来创建新文章太麻烦了, obsidian 提供的模板可以方便的创建新的文章.
在 source 下创建_obsidian/PostTemplate.md文件, 填写以下内容:

---
title: {{title}}
author: {yourname}
date: {{date}}
tags: []
---

之后, 在设置-核心插件-模板中添加_obsidian 文件夹, 并在核心插件中启用模板, 就可以通过点击侧边栏中的模板快速创建 hexo 文章模板了

hexo 的 catagorys 维护相对较为复杂, 可以选择使用 hexo 的  hexo-auto-category插件, 在项目根目录下 npm install 即可, 插件会在部署时自动完成 category 的维护. 我们只需要在_posts 文件夹下创建文件夹即可格局文件夹进行 category 分类.

此外, obsidian 的prettier插件可以自动识别文章格式并添加 update 与 modify 时间, 相当推荐安装.
超链接,图片等目前采取的方案是改写 md 格式, 其他的一些配置我没有完全采用, 可以进一步参考博客Hexo + Obsidian + Git 完美的博客部署与编辑方案 | EsunR-Blog实现其他功能.

后记

到此为止, 你应该已经完成了整一个博客和工作流的搭建! 再来回顾一下博客工作流:

• obsidian 中在 category 对应文件夹下创建新的 md 文件;
• 使用模板快速完成文件信息的填充
• 编写博客内容
• 在 obsidian 中执行commit & push命令
• 博客文章顺利上线啦!

后续应该会围绕美化、图床、CDN 加速、md 格式转换等再补充一篇文章，但那也是后话啦。
如果发现文中错误或问题，欢迎提问或私信（，要是感觉有帮助的话欢迎访问仓库求一个 star~

迁移至新电脑

2024.09 Update:

在无特殊情况下采用从 Git 仓库恢复会更加方便，具体流程如下：
默认完成 Git(username, email, SSH Key)的配置，完成 Obsidian 的安装

1. 在根路径下新建 Blog 文件夹
2. 在 Terminal 中打开，安装 nodejs(网页链接)与 hexo 及其他插件

npm install -g hexo-cli
#必要
npm install hexo-renderer-pug
npm install hexo-renderer-sass
npm install hexo-generator-search
# 如果需要添加订阅功能
npm install hexo-generator-feed

3. 使用 SSH 同步仓库（确保仓库已经更新到最新）

git clone git@github.com:[username]/[SourceRepo]

4. 测试 hexo 与 git 部署：

cd [SourceRepo]
hexo -v
hexo g
# hexo s

5. 在 Obsidian 中打开 SourceRepo 重要！不然插件无法正常加载 ，测试运行

以下为原始教程：

相比起原本的本地部署方案，该方案的一大优点便是便于迁移与恢复，以下仅考虑了最差的情况——从一穷二白开始恢复博客系统。

1. 完成 nodeJs，hexo，picGo，git 的安装以及 SSH Key 的配置（参考上文）与用户设置

注意! 本地生成的 SSH Key 与 github 中存储的并不相同，注意替换或修改，PicGo 配置需要使用到之前保存的 token；
如果是直接复制过来的仓库，那大概率在目录下直接安装 hexo 就可以了，然后直接尝试运行hexo g，hexo s 看看能不能正常部署。

2. 完成插件安装（根据之前安装了哪些插件选择，以下为示例）

#必要
npm install hexo-renderer-pug
npm install hexo-renderer-sass
npm install hexo-generator-search

#选择性安装
# 如果需要添加订阅功能
npm install hexo-generator-feed
# 流程图功能
npm install hexo-filter-flowchart --save
# Emoji
npm install hexo-filter-github-emojis --save
# 搜索功能
npm install hexo-generator-search --save
# 数学公式
npm install hexo-renderer-mathjax --save

3. 将仓库拉取到本地
   git bash 中拉取源码仓库：

git clone https://github.com/{your name}/{blog-repo}

如果你严格 follow 了全部的安装步骤，理论上已经可以在本地测试了：

hexo g
hexo s

4. obsidian 打开源码文件夹，obsidian 会自动识别安装的插件并完成相关配置。
5. 与之前一样上传仓库，测试 github Action 能否正常执行。

如果在 github Action 部分出现Invalid username or password. 问题，可能是配置 PicGo 时手忙脚乱刷新了 Token，更新一下Settings -- Secrets and variables -- Newrepository secret中的 GITHUBTOKEN 字段。

修改自定义域名

访问[SourceRepo]/source/CNAME，修改为新的自定义域名

附录

hexo 指令

hexo n "我的博客" == hexo new "我的博客" #新建文章
hexo g == hexo generate #生成
hexo s == hexo server #启动服务预览
hexo d == hexo deploy #部署

hexo server #Hexo会监视文件变动并自动更新，无须重启服务器
hexo server -s #静态模式
hexo server -p 5000 #更改端口
hexo server -i 192.168.1.1 #自定义 IP
hexo clean #清除缓存，若是网页正常情况下可以忽略这条命令