Hexo 博客全自动写作与发布指引（Typora + GitHub Actions 方案）

发表于 分类于

本文是这套博客方案的完整使用指引：从写下第一个字到全网上线，本地只需要 Typora + Git，无需懂 Node.js，无需手动部署。想复刻同款方案或加入协作的读者，按此文操作即可。

一、方案概览

1
2
3
4
5
Typora 写作（Windows）
    ↓ git commit & push（source 分支）
GitHub Actions 自动构建（hexo generate）
    ↓ 自动发布
gh-pages 分支 → GitHub Pages → CDN → 读者
  • 写作：Typora 编辑 Markdown，图片即贴即用
  • 发布：git push 即全部，约 1 分钟后上线
  • 环境：Windows 11 + WSL2（仅本地预览时需要），核心流程零依赖

仓库结构是单仓库双分支：source 分支放源码（文章 + 配置），gh-pages 分支由 Actions 自动构建发布，不要手工改动。

二、写一篇新文章（完整流程）

1. 新建文件

在 source/_posts/ 下新建 YYYYMMDD-标题.md，顶部写 front-matter：

1
2
3
4
5
6
7
8
9
---
title: "文章标题"
slug: "20260730-文章标题"    # 与文件名保持一致（见下方说明）
date: 2026-07-30 15:00:00
categories:
  - Daily
tags:
  - Practice                 # 注意：不要写成 - # Practice
---

三个易错点：

  • URL 由文件名决定，不由 slug 决定：实测在当前 Hexo 6 环境下，front-matter 的 slug 不会生效，文章 URL 实际取文件名（YYYYMMDD-标题.md → /年/月/日/文件名/）。因此文件名定好后不要改，改名等于换 URL，旧链接全失效；同时保持 slug 与文件名一致，避免误导
  • 归档位置由 date 决定：URL 里的 /年/月/日/ 取自 front-matter 的 date，与文件名里的日期可以不同（补发旧文时常见），属正常现象
  • tags 不要加 # 号：front-matter 是 YAML，# 是注释符，- # Practice 会被解析为空标签（本博客 17 篇文章曾因此标签全丢）

2. 插图（即贴即用）

Typora 一次性设置：**偏好设置 → 图像 → 插入图片时「复制图片到指定路径」，填 ./../images**。

之后粘贴图片即可：

  • 图片自动存入 source/images/，Typora 里即时可见
  • 构建时 scripts/rewrite-images.js 自动把路径改写为线上根路径，无需关心
  • 提交时 git add source 把图片和文章一起带上

3. 写草稿（可选）

不想立即发布的文章放 source/_drafts/，push 也不会上线。写完移回 _posts/ 即可。

4. 本地预览（可选）

Typora 只渲染通用 Markdown，看不到主题真实样式。想预览真实效果：

1
2
3
# WSL 中
cd ~/blog
npx hexo server          # Windows 浏览器打开 http://localhost:4000

5. 发布

1
2
3
git add source
git commit -m "post: 文章标题"
git push

推送后约 1 分钟：GitHub Actions 自动完成 npm install → hexo generate → 部署 gh-pages → GitHub Pages 构建，全程无需干预。仓库 Actions 标签页可看进度，绿色即成功。

6. 关于 CDN 缓存（重要）

站点前面有 CDN 加速，发文后线上可能延迟约 10 分钟才更新（CDN 节点缓存）。看不到新文章时：

  1. 先 Ctrl + F5 强刷浏览器
  2. 还不行就到 CDN 控制台手动刷新全站缓存

（后续迁移到 Cloudflare 后，工作流已内置自动刷新步骤，配置好 Secrets 即可”发文即见”。）

三、日常维护速查

需求 操作
改文章 直接编辑 _posts/ 里的文件，push
删文章 删除对应 .md 文件，push
改标签/分类 编辑 front-matter，push
改文件名 等于更换文章 URL（slug 不生效），避免对已发布文章使用
回滚 在 source 分支 git revert 后 push，不要依赖 gh-pages 历史
排障入口 浏览器 F12 控制台——服务端 curl 正常不代表浏览器执行正常

四、这套方案的技术栈（供复刻参考）

  • Hexo 6 + NexT 8（Gemini）：主题务必用 NexT 8，5.x 老版本与 Hexo 6 有多处兼容坑（swig 渲染器、菜单编码、i18n 命名），我们全部踩过
  • 部署：GitHub Actions + peaceiris/actions-gh-pages，源码分支推送即触发
  • 图片：弃用外链图床，图片随仓库走（source/images/），无外链失效风险
  • 工作目录：单一副本 ~/blog（WSL 的 Linux 原生目录，hexo server 保存即自动重建）；Typora 经 \\wsl$\Ubuntu\home\sam\blog 打开写作
  • 完整工程说明见仓库 README.md

五、写作约定清单（发文前自查）

  • 文件名 YYYYMMDD-标题.md（它决定 URL，定好后不再改）
  • front-matter 五项齐全（title / slug / date / categories / tags），且 slug 与文件名一致
  • tags 不带 # 号
  • 图片走的是粘贴归档（source/images/），不是本地绝对路径
  • git add source 包含了新增的图片
  • push 后去 Actions 确认绿色

按此清单操作，写作就是纯粹的文字工作，其余全部交给自动化。