秋千AkiSenn生活笔记
← 所有文章
/ 18 分钟阅读 / 4478 字 / 更新于 2026.10.05

GitHub + Hexo + AutuSwing + Workers：搭建个性化博客

#GitHub#网站#AutuSwing#HexoThemes#Hexo#Cloudflare#Workers

前言

想拥有一个自己决定样式、用来记录生活和技术的博客，又不想维护服务器，可以从 Hexo 开始：用 Markdown 写文章，用主题安排页面，再交给托管平台发布。

这篇文章以 Windows + Git Bash 为例，使用 AutuSwing 配置博客，把完整源码存入 GitHub，再直接在 Cloudflare 创建 Workers 项目，连接源码仓库，让 Workers 自动编译和发布网站。以后更新文章，只要提交并推送源码，网站就会跟着更新。

自定义域名是本文的必做步骤。 workers.dev 在中国大陆存在访问限制，不能作为面向大陆读者的正式入口。请提前准备一个自己控制的域名，完成 Cloudflare 接入和 Workers 绑定后，再对外分享网址；自定义域名的实际访问情况仍需在目标网络验证。

更新说明（2026 年 10 月）：本文已改用 AutuSwing 和 Workers。主题配置依据本地 AutuSwing 0.1.0 编写；主题仓库目前为私密仓库，正式版尚未发布，只有获得仓库权限的账号才能下载。后续公开版的安装方式和配置，请以仓库说明为准。

Hexo、AutuSwing、GitHub 与 Workers 的建站流程

图 1：本地写作和预览，GitHub 保存源码，Workers 自动生成网站，读者通过自定义域名访问。

一、先弄清楚各部分的分工

工具在这个博客里负责什么
Hexo把 Markdown 文章生成 HTML 等静态文件
AutuSwing提供博客外观、文章排版、导航与阅读功能
GitHub保存文章、配置、主题和依赖文件，触发云端构建
Cloudflare Workers自动构建、托管生成的网站，并连接自定义域名

Workers 可以托管静态资源，也能在以后接入服务端功能。本教程先完成静态博客，不需要另外购买服务器，也不需要先发布到 GitHub Pages 或 Cloudflare Pages。

请记住两个目录：source/ 是原稿和资源，public/ 是 Hexo 生成的网站。改文章时编辑前者，后者随时可以重新生成。

二、准备环境与 GitHub 授权

1. 安装 Node.js 和 Git

下载安装 Node.js 的受维护 LTS 版本，以及 Git for Windows。保留 npm、加入 PATH 和 Git Bash 等常用选项。

本文使用 Hexo 8 与 AutuSwing 0.1.0，要求 Node.js 至少为 20.19.0；最低版本要求不等于推荐继续使用旧版本。版本对应关系见 Hexo 官方文档。

安装后重新打开 Git Bash，执行：

1
2
3
4
5
6
node -v
npm -v
git --version

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

三条检查命令都应返回版本号。Git 的名字和邮箱只是提交署名，访问私密仓库还需要授权。

下面的 /e/ 路径和命令都以 Git Bash 为准：Windows 的 E:\hexo-blog 在这里写作 /e/hexo-blog。

2. 配置 SSH 密钥

先检查是否已有密钥：

1
ls -al ~/.ssh

如果已有正在使用的密钥，直接使用对应公钥，不要覆盖。没有密钥时生成一对：

1
ssh-keygen -t ed25519 -C "你的邮箱"

按提示确认保存路径，可以设置口令。默认生成 id_ed25519 和 id_ed25519.pub。启动代理并加载私钥：

1
2
3
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub

复制公钥的完整一行，在 GitHub 的 Settings → SSH and GPG keys → New SSH key 中添加，类型选择 Authentication Key。不要上传没有 .pub 后缀的私钥。

1
ssh -T git@github.com

首次连接时，先对照 GitHub 官方 SSH 指纹核验，再确认连接。出现 You've successfully authenticated 表示认证成功；GitHub 不提供交互式 shell，因此这条测试命令可能仍返回非零退出码。

SSH 授权成功不代表拥有所有私密仓库的权限。克隆 AutuSwing 前，还需要当前账号获得该仓库的访问权限。

GitHub SSH 公钥与私钥的区别

图 2：公钥交给 GitHub，私钥留在自己的电脑。

三、创建 Hexo 博客并完成本地预览

本文将博客放在 E:\hexo-blog，在 Git Bash 中执行：

1
2
3
4
5
6
7
8
npm install -g hexo-cli
cd /e/
hexo init hexo-blog
cd /e/hexo-blog
npm install
npm install hexo@^8.1.2 hexo-renderer-ejs@^2 hexo-renderer-marked@^7
hexo version
hexo server

打开终端提示的地址，通常是 http://localhost:4000。能看到默认主题和示例文章，就说明基础环境可用。按 Ctrl + C 停止预览服务。

除特别说明外，后面的命令都在 博客根目录 /e/hexo-blog 执行。不要进入 source/_posts/ 后再安装依赖或执行构建。

四、安装并配置 AutuSwing

1. 下载主题完整源码

有私密仓库权限时，可以先把主题克隆到博客目录之外，再导出到博客中：

1
2
3
4
git clone git@github.com:AkiSenn/hexo-theme-autuswing.git /e/hexo-theme-autuswing
cd /e/hexo-blog
mkdir -p themes/autuswing
git -C /e/hexo-theme-autuswing archive HEAD | tar -x -C themes/autuswing

这里把主题作为完整文件放入博客源码，避免嵌套 Git 仓库导致云端只有一个空主题目录。上面的下载目录如已存在，直接使用已有仓库，或换一个未占用的目录。

也可以用有权限的 GitHub 账号下载 ZIP，解压后把主题根目录的内容放进 themes/autuswing/。确认直接存在这些文件，而不是多套了一层目录：

1
2
3
4
5
6
7
8
9
10
themes/autuswing/
├── _config.yml
├── package.json
├── package-lock.json
├── layout/
├── scripts/
├── lib/
├── source/
├── assets/
└── vendor/

不要只复制模板和样式。主题的脚本、资源和本地数学公式文件也属于完整主题的一部分。没有权限时，先等待正式版或联系作者获取授权，不能把私密仓库的 404 当成下载地址失效。

2. 安装主题依赖

根目录的 npm install 不会自动安装主题子目录里的依赖，需要再执行：

1
npm ci --prefix themes/autuswing --omit=dev

这是基于主题提供了 package-lock.json 的写法。如果获得的主题包确实没有锁文件，改用 npm install --prefix themes/autuswing --omit=dev，并将生成的锁文件一起保存；后续云端构建统一使用 npm ci。

3. 区分站点配置和主题配置

编辑博客根目录的 _config.yml，修改已有字段，不要在文件末尾重复添加同名字段：

1
2
3
4
5
6
7
8
9
title: 我的个人博客
subtitle: 记录生活与技术
description: 一个使用 Hexo 与 AutuSwing 搭建的博客
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai
url: https://blog.example.com
root: /
theme: autuswing

把 blog.example.com 换成准备绑定的正式域名。这里使用独立域名的根路径，不需要 GitHub 项目站点那样的仓库名子路径。

然后复制主题默认配置：

1
cp themes/autuswing/_config.yml _config.autuswing.yml

此命令只在第一次创建个人配置时执行，已有文件不要直接覆盖。以后主要编辑根目录的 _config.autuswing.yml，升级主题时保留自己的设置。

Hexo 与 AutuSwing 的目录和配置分工

图 3：站点设置写在 _config.yml，个人主题设置写在 _config.autuswing.yml。

4. 设置头像、菜单和个人介绍

把自己的头像和站点图标分别放到 source/img/my-avatar.png、source/img/my-favicon.png。在 _config.autuswing.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
avatar: /img/my-avatar.png
favicon: /img/my-favicon.png
since: 2026
color_mode: auto

menu:
  Home: /
  Archives: /archives/
  Tags: /tags/
  Links: /links/
  About: /about/

social:
  GitHub: https://github.com/YOUR_USERNAME
  Email: mailto:you@example.com

profile:
  author: 你的名字
  subtitle: 记录生活与技术
  email: you@example.com
  aboutme: '<p>你好，欢迎来到我的博客。</p>'

friends:
  - name: Hexo
    url: https://hexo.io
    description: 静态博客框架

菜单键名由主题语言文件显示为相应文案，值则是链接地址。color_mode: auto 表示跟随系统配色，访客也可以通过主题开关切换。

当前 AutuSwing 会生成标签、分类、关于和友链页面，个人介绍来自 profile.aboutme，友链来自 friends。已有同路径页面时，以已有页面为准。如果从旧主题迁移，先检查 source/about/、source/tags/、source/links/，避免旧页面内容让你误以为新配置没有生效。

想自己写“关于”页，也可以执行 hexo new page about，然后编辑生成的 source/about/index.md。profile.aboutme 和其他自定义 HTML 字段只填自己确认过的内容。

5. 调整外观与阅读功能

同样在个人主题配置中修改已有字段：

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
cards:
  enable: true
  article: true
  hover: true
  blur: 24

appearance:
  base_font_size: 16
  sidebar_width: 272
  width: 1680
  radius: 18
  background_image: false
  theme_switch: true

reading:
  toc: true
  progress: true
  words_per_minute: 250

article:
  excerpt: auto
  excerpt_length: 200
  lightbox: true
  lazyload: true
  updated: true
  word_count: true
  reading_time: true

search:
  enable: true
  content: true

feed:
  enable: true

seo:
  sitemap: true
  robots: true
  json_ld: true
  social_image: /img/my-avatar.png

edge:
  provider: cf

如果要使用背景图，把图片放进 source/img/，再将 appearance.background_image 改成类似 /img/wallpaper.webp 的路径。它是 appearance 下的字段，不能套用旧主题的顶层配置。

主题已包含搜索索引、RSS/Atom、站点地图和文章短链接功能，先使用内置配置，再考虑额外插件。旧博客里生成相同文件的插件需要逐个检查，避免重复输出。

主题默认启用文章短链接，并把标识保存在文章的 abbrlink 字段中。迁移旧文章时保留原有 abbrlink，不要为了换主题删除它。

AutuSwing 常用配置对应的页面区域

图 4：先完成头像、导航和阅读设置，再逐步调整外观。配图为配置示意，不是实际主题截图。

配置完成后检查：

1
2
3
npx hexo clean
npx hexo generate
npx hexo server

打开首页、文章、标签、关于和友链页面，检查桌面与手机宽度下的布局；确认图片、搜索、目录和深浅色切换可用，再停止服务。

五、写第一篇文章并添加配图

1
npx hexo new "我的第一篇文章"

打开 source/_posts/ 中生成的 Markdown 文件，按需填写头部信息：

1
2
3
4
5
6
7
8
9
---
title: 我的第一篇文章
date: 2026-10-05 10:00:00
tags:
  - 生活
categories:
  - 随笔
description: 这篇文章的简短介绍。
---

头部之后写正文，用 ##、### 组织标题。需要手动设置首页摘要分界时，插入 <!-- more -->。

文章图片建议放进独立目录，例如 source/img/posts/my-first-post/，正文这样引用：

1
![图片说明](/img/posts/my-first-post/example.webp)

浏览器访问路径不含 source/。文件名尽量简短，控制图片体积，并保留说明文字。Windows 对文件名大小写较宽松，云端 Linux 则区分大小写，所以文件名与引用必须完全一致。

六、把完整源码保存到 GitHub

1. 创建源码仓库

在 GitHub 新建一个仓库，例如 hexo-blog-source。当前主题尚未公开，使用它的博客源码仓库也先设为 Private，避免把未发布主题随源码公开。 仓库可以是私密的，Workers 通过你授予的 GitHub 权限读取它。

新仓库先不要勾选自动创建 README、许可证或 .gitignore，这样第一次推送更直接。这里保存的是完整 Hexo 源码，仓库名不必使用 用户名.github.io。

2. 检查忽略文件和主题文件

根目录的 .gitignore 至少应包含：

1
2
3
4
5
node_modules/
public/
db.json
.deploy*/
*.log

不要忽略 themes/autuswing/、文章、图片和配置。依赖目录不上传，但根目录与主题目录的 package.json、package-lock.json 都要上传。

按前面的导出方式安装主题后，主题文件属于博客仓库本身。云端不依赖你电脑上的其他目录，也不需要再次登录另一个私密主题仓库下载。

3. 首次推送

先运行 git status。如果提示当前目录不是 Git 仓库，再执行 git init。对于刚建立的新博客，继续执行：

1
2
3
4
5
6
git add .
git status
git commit -m "Initialize Hexo blog with AutuSwing"
git branch -M main
git remote add origin git@github.com:YOUR_USERNAME/hexo-blog-source.git
git push -u origin main

把 YOUR_USERNAME 换成自己的 GitHub 用户名。已有博客若已经设置了远程地址，先用 git remote -v 检查，按现有仓库情况处理，不要重复执行 git remote add origin。

推送后，打开 GitHub 仓库，确认能看到 source/、themes/autuswing/、两份配置，以及根目录和主题的依赖文件。主题目录必须能展开看到源码，不能只是一个子模块链接。

七、创建 Workers 项目并连接源码仓库

1. 从 GitHub 导入

登录 Cloudflare 控制台，进入 Workers & Pages → Create application（创建应用），选择创建 Worker 并从 Git 仓库导入；界面通常显示 Import a repository / Connect GitHub。

授权 Cloudflare 访问 GitHub，选择刚才的 hexo-blog-source 仓库。只授权所需仓库即可。如果列表里找不到私密仓库，检查 GitHub App 的仓库访问范围是否包含它。

这个过程直接连接 Hexo 源码仓库。不要选只有 index.html 等生成文件的旧发布分支，也不要创建 Pages 项目。入口说明可参考 Workers Builds 官方文档。

2. 填写构建与部署设置

设置项本文示例
Worker 名称hexo-blog
Git 仓库hexo-blog-source
生产分支main
根目录仓库根目录；有该输入框时保留默认
Build command（构建命令）见下方第一条命令
Deploy command（部署命令）见下方第二条命令

构建命令：

1
npm ci --prefix themes/autuswing --omit=dev && npx hexo clean && npx hexo generate

部署命令：

1
npx wrangler deploy --name hexo-blog --assets ./public

Workers 会按根目录的依赖文件安装项目依赖；构建命令再安装 AutuSwing 的独立依赖，随后由 Hexo 生成 public/。部署命令把这个目录作为静态资源发布。

两条命令填写在 Cloudflare 控制台，由云端执行。你不用先在本地安装 Wrangler 或执行登录命令。Worker 名称改了，部署命令里的 --name 也要一起改；已有 Wrangler 配置的仓库，还应检查其中的名称、资源路径和域名设置是否一致。

构建环境的 Node.js 版本要满足前面的要求。可以在构建变量里设置 NODE_VERSION 为本地验证过的完整版本号，以 node -v 输出为准并去掉开头的 v。构建命令、部署命令和构建变量的说明见 Workers Builds 配置文档。

Workers 连接源码仓库与自动构建设置示意

图 5：连接源码分支，安装主题依赖，生成 public/，再发布静态资源。

3. 保存并检查第一次构建

点击 Save and Deploy / Deploy，在构建日志里确认根目录依赖安装、主题依赖安装、Hexo 生成和静态资源部署全部成功。日志中应该能看到 public/ 中的文件被发布。

控制台可能会提供 workers.dev 地址，但本文不以它作为上线验收地址。继续完成下一节的自定义域名绑定，再通过正式域名检查网站。

八、必须完成：绑定 Workers 自定义域名

1. 先让域名在 Cloudflare 生效

准备自己控制的域名，例如 example.com，在创建 Worker 的同一个 Cloudflare 账号下添加域名。

按 Cloudflare 提示导入并检查现有 DNS 记录，尤其是已有网站和邮箱的记录。随后到域名注册商的控制台，将域名的 Nameservers（名称服务器 / NS）改为 Cloudflare 分配的两个地址。等待 Cloudflare 将站点状态显示为 Active。

这里是修改域名的 NS，不是在 DNS 列表里随意新增两条 NS 记录，也不是把域名转移注册商。已经接入同一 Cloudflare 账号并处于 Active 状态的域名，可以直接进入下一步。

2. 将正式域名添加到 Worker

建议先使用一个明确的博客子域名，例如 blog.example.com：

  1. 打开 Workers & Pages，选择 hexo-blog。
  2. 进入 Domains（域名），添加已有域名，选择 Custom Domain（自定义域名）。部分界面入口仍在 Settings → Domains & Routes → Add → Custom Domain。
  3. 输入完整主机名 blog.example.com，按提示确认添加。
  4. 等待域名与证书状态正常，再打开 https://blog.example.com。

Cloudflare 会为 Custom Domain 创建相应 DNS 记录并管理证书。不要再手动添加一条指向 workers.dev 的 CNAME 来代替绑定。 具体要求见 Workers 自定义域名文档；新版域名入口见 Domains 标签页说明。

如果同一个主机名已有指向 GitHub Pages 或 Cloudflare Pages 的 CNAME，先记录原设置，在准备切换时解除旧平台的域名绑定，并清理该主机名的冲突记录，再添加 Worker 自定义域名。只处理要迁移的博客主机名，保留其他网站和邮箱记录；正式域名验证成功前，保留旧项目以便需要时恢复。

Workers 自定义域名接入与绑定流程

图 6：域名接入 Cloudflare → Worker 添加 Custom Domain → DNS 与证书就绪 → 正式网址验收。

3. 统一博客网址并验收

再次确认根目录 _config.yml：

1
2
url: https://blog.example.com
root: /

使用自己的正式域名，不要写成 workers.dev。如果在绑定时换了域名，提交配置并推送，让 Workers 重新构建：

1
2
3
git add _config.yml
git commit -m "Set production blog domain"
git push

配置原本就正确时，不必为了这一步创建空提交。Workers 不依靠 GitHub Pages 的 source/CNAME 文件绑定域名；从旧站迁移过来的这个文件不应再被当作 Workers 的域名配置。

通过正式域名检查首页、文章内页、图片、搜索、RSS 和站点地图。关闭浏览器缓存或用无痕窗口，并在实际面向的大陆网络上测试访问。完成这些检查，才算上线。

example.com 与 www.example.com 是两个不同主机名。如果还需要另一个入口，应额外配置绑定或重定向，并让博客的 url 保持一个统一的正式地址。

九、以后如何更新文章和迁移电脑

1. 日常发布

在博客根目录执行：

1
npx hexo new "新文章标题"

写好文章、放好图片，先本地预览：

1
2
3
npx hexo clean
npx hexo generate
npx hexo server

检查完成后按 Ctrl + C，提交并推送：

1
2
3
4
git add .
git status
git commit -m "Add a new post"
git push

Workers 监听 main 分支的新提交，自动构建并发布。等本次部署成功后再检查正式域名。这个流程不用 hexo deploy，也不用把 public/ 手动上传到 GitHub。

2. 换电脑或恢复博客

1
2
3
4
5
6
git clone git@github.com:YOUR_USERNAME/hexo-blog-source.git
cd hexo-blog-source
npm ci
npm ci --prefix themes/autuswing --omit=dev
npx hexo generate
npx hexo server

完整源码与锁文件都在仓库里，换电脑就能恢复。GitHub 是一份远程副本，重要文章和原始图片也建议保留本地备份。

十、常见问题

现象优先检查
主题仓库显示 404 或 Repository not foundAutuSwing 仍是私密仓库；确认登录账号和仓库权限
本地能运行，Workers 找不到主题GitHub 上是否真的包含 themes/autuswing/ 完整文件，有无子模块或本机目录链接
缺少 cheerio、clean-css、terser 等依赖是否执行主题目录的依赖安装，云端构建命令是否包含该步骤
YAML 报错或配置不生效用空格缩进，不用 Tab；检查重复字段、大小写和字段层级
修改主题后仍显示旧内容重启预览服务，执行 hexo clean 后重建；检查是否有已有页面覆盖自动页面
云端图片 404图片是否提交，路径是否省去 source/，文件名大小写是否一致
Worker 部署提示名称不匹配控制台 Worker 名称、部署命令 --name 与已有 Wrangler 配置是否一致
自定义域名无法添加域名是否在同账号下 Active，目标主机名是否已有冲突 CNAME 或旧平台绑定
部署成功但大陆打不开 workers.dev完成必做的自定义域名绑定，通过正式域名验收
正式域名没有显示最新文章确认推送分支、最新构建结果和域名绑定的 Worker，再检查缓存

博客建好之后，写作就变成了一个固定习惯：编辑 Markdown、检查预览、推送源码。主题和托管平台把发布流程接起来，你可以把更多时间留给内容。

微博 X Telegram QQ

搜索

搜索文章、标签或关键词…