1 介绍

Hexo 是一款简洁、高效且功能强大的博客发布工具，支持 Markdown 格式，拥有丰富的插件和主题。我通常使用 Obsidian 编写文档，然后通过 Hexo 的命令行工具生成静态网页并发布到网站。

本文简要介绍了如何在本地使用 Docker 搭建 Hexo 环境，并将 Markdown 格式的内容转换为网页，最终部署到 github.io 作为个人网站。

2 本地环境

2.1 使用镜像

Hexo 依赖于 JavaScript 开发环境，我使用了 Hexo 的 Docker 镜像，该镜像基于轻量且稳定的 Alpine 版本，整个镜像仅有几十兆，并配备了基本的 vi 编辑器。我的宿主机运行的是 Ubuntu 系统，具体操作如下：

1
$ docker pull taskbjorn/hexo:alpine-latest

在镜像外建立数据目录：

1
2
$ sudo mkdir /exports/hexo_data -p # 数据存放在 docker 之外
$ sudo chmod 777 /exports/hexo_data # 注意始终保证目录权限可被docker访问

第一次启动镜像时，数据会安装到 /home/hexo/.hexo 目录，因此速度较慢。以后再次启动时，速度会提升。正常启动后，可通过 http://localhost:4000 端口访问 hexo 创建的静态网站，生成新内容时自动更新，无需重启服务。

1
$ docker run -it --rm --name my_hexo_container --privileged=true --network=host -v /exports/hexo_data:/home/hexo/.hexo taskbjorn/hexo:alpine-latest

以 root 身份进入 Docker，安装常用工具，然后在另一个终端进入：

1
2
3
4
5
$ docker exec -u root -it my_hexo_container sh
$ apk update
$ apk add pandoc
$ apk add openssh
$ exit

建议保存 docker image：

1
$ docker commit my_hexo_container taskbjorn/hexo:alpine-250707

以默认用户身份进入 Docker 后，可以看到当前用户为 hexo，且项目文件已在当前目录下创建完毕：软件包安装在 node_modules 目录中，source 目录存放 markdown 等源数据，生成的文件位于 public 目录，主要的配置文件为 _config.yml。

1
$ docker exec -it my_hexo_container sh

2.2 配置文件

_config.yml 是最基本的配置文件，至少需要设置其 site 部分：

1
2
3
4
5
6
title: '标题'
subtitle: '副标题'
description: '网站描述'
author: 作者
language: zh-Hans
timezone: 'Asia/Shanghai'

2.3 基本操作

1
2
3
4
$ hexo cl # hexo clean 清除缓存
$ hexo g # hexo generate 生成静态网页
$ hexo d # hexo deploy 部署
$ hexo s # hexo server 启动服务预览，由于docker已经启动了服务，无需此操作

2.4 Markdown 规范

通过 markdown 生成的网页，如果不设置文件头，则列表中只能显示文件创建日期：

因此，至少需要设置 title 才能正常显示，一般设置 title, author, date, tags，Obsidian 的 hexo 模板如下：

1
2
3
4
5
6
7
---
title: <% tp.file.title %>
author: xieyan0811
date: <% tp.file.creation_date() %>
updated: <% tp.file.last_modified_date() %>
tags:
---

3 部署博客到 github.io

3.1 配置 github 免密环境

3.1.1 方法一

1
2
3
$ git config --global user.email 你的邮箱
$ git config --global user.name 你的用户名
$ ssh-keygen -t rsa -C 你的邮箱 # 一路回车

如果提示找不到 ssh-keygen，可能是 docker 环境中未安装 openssh 工具集，参见上面的安装工具部分。

将 /home/hexo/.ssh/id_rsa.pub 内容加入 github，具体方法是：

https://github.com/settings/keys add ssh key

3.1.2 方法二

也可以把宿主机的 rsa 复制过来，形如：

1
$ cp 宿主机/.ssh/id_rsa* /home/hexo/.ssh/

3.1.3 测试 github 环境

设置好后，查看能否正常使用：

1
$ ssh git@github.com  # 正常结果形如: You've successfully authenticated

如遇到 github.com 22 端口连不通

1
ssh: connect to host github.com port 22: Operation timed out

尝试 443 端口

1
$ ssh -T -p 443 git@ssh.github.com

如果 443 正常，则要设置默认的 github 端口

1
2
3
4
5
6
$ vi /home/hexo/.ssh/config
# 输入以下内容
Host github.com
  HostName ssh.github.com
  Port 443
  User git

为保留 docker 中的内容，建议设置后再 commit 一下：

1
docker commit my_hexo_container taskbjorn/hexo:alpine-250707

3.1.4 配置文件

修改配置文件 _config.yml，设置部署服务

1
2
3
4
deploy:
  type: 'git'
  repo: git@github.com:用户名/用户名.github.io # 注意这里不是http地址 
  branch: master

3.1.5 部署

1
2
3
$ npm install hexo-deployer-git # 安装 hexo 的 git 插件
$ hexo g # 生成静态网页
$ hexo d # 部署到 github.io

正常执行后，可以看到 public 目录内容被更新到 github.io 主页，内容也不多，只有 demo 时不到 1M。