blog: 用GitHub Actions自动构建EGO博客

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lujun9972

Emacs之怒/用GitHub Actions自动构建EGO博客.org

@@ -0,0 +1,210 @@
+#+TITLE: 用GitHub Actions自动构建EGO博客
+#+AUTHOR: lujun9972
+#+CATEGORY: Emacs之怒
+#+DATE: [2026-04-11 周五]
+#+OPTIONS: ^:{}
+
+* 背景
+
+我的博客 [[https://lujun9972.github.io/][暗无天日]] 使用 [[https://github.com/lujun9972/EGO][EGO]]（Emacs + Git + Org-mode）作为静态站点生成器。源文件是 ~.org~ 格式，存放在 ~source~ 分支；生成的 HTML 存放在 ~master~ 分支，通过 GitHub Pages 托管。
+
+一直以来，我都是在本机执行 ~auto_publish.el~ 来发布博客。但既然用了 GitHub，为什么不把构建过程也自动化呢？于是我开始折腾用 GitHub Actions 来自动构建博客。
+
+* 最终效果
+
+每次 ~push~ 到 ~source~ 分支时，GitHub Actions 会自动：
+1. 用 EGO 将 ~.org~ 文件转换为 HTML
+2. 将生成的 HTML 推送到 ~master~ 分支
+3. GitHub Pages 自动部署
+
+顺带还会在 Habitica 上完成"写博客"任务打个卡（游戏化激励）。
+
+* 实现过程
+
+** 第一步：改造 auto_publish.el
+
+原来 ~auto_publish.el~ 里的路径都是硬编码的：
+
+#+begin_src emacs-lisp
+(setq load-path (cons "~/EGO/" load-path))
+(setq load-path (cons "~/csdn-publish/" load-path))
+(setq load-path (cons "~/toutiao/" load-path))
+#+end_src
+
+这在本地没问题，但在 CI 环境里路径完全不同。所以我把所有硬编码路径改为从环境变量读取，保留默认值确保本地兼容：
+
+#+begin_src emacs-lisp
+(setq load-path (cons (or (getenv "EGO_DIR") "~/EGO/") load-path))
+(setq load-path (cons (or (getenv "CSDN_DIR") "~/csdn-publish/") load-path))
+(setq load-path (cons (or (getenv "TOUTIAO_DIR") "~/toutiao/") load-path))
+#+end_src
+
+~ego-project-config-alist~ 中的 ~:repository-directory~ 和 ~:store-dir~ 也做了类似处理：
+
+#+begin_src emacs-lisp
+`(("blog" :repository-directory ,(or (getenv "REPO_DIR") "~/source")
+   ...
+   :store-dir ,(or (getenv "STORE_DIR") "~/web")))
+#+end_src
+
+同时删除了已废弃的 CSDN 和头条发布代码（对应的包在本机也不存在了），精简了脚本。
+
+** 第二步：编写 GitHub Actions Workflow
+
+最终的 workflow 文件 ~.github/workflows/github-action.yml~：
+
+#+begin_src yaml
+name: 提交 habitica 任务 + 构建博客
+on:
+  push:
+    branches: [source]
+
+permissions:
+  contents: write
+
+jobs:
+  Finish-Habitica-Tasks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out habash code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          repository: nasfarley88/habash
+      - name: 确保 habash 可执行
+        run: chmod +x ./habash
+      - name: 提交 habitica 任务
+        run: |
+          set -x
+          ./habash up "写博客"
+        env:
+          HABITICA_TOKEN: ${{ secrets.HABITICA_TOKEN }}
+          HABITICA_UUID: ${{ secrets.HABITICA_UUID }}
+
+  Build-Blog:
+    runs-on: ubuntu-latest
+    env:
+      EGO_DIR: ${{ github.workspace }}/EGO
+      REPO_DIR: ${{ github.workspace }}
+      STORE_DIR: ${{ github.workspace }}/web
+      REPO: https://github.com/lujun9972/${{ github.event.repository.name }}
+    steps:
+      - name: Checkout 博客源文件
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: source
+
+      - name: Checkout EGO
+        uses: actions/checkout@v4
+        with:
+          repository: lujun9972/EGO
+          path: EGO
+
+      - name: Checkout master 分支到 store-dir
+        run: |
+          git clone --branch master --single-branch \
+            https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git \
+            "$STORE_DIR"
+          cd "$STORE_DIR"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: 安装 Emacs 和系统依赖
+        run: sudo apt-get update && sudo apt-get install -y emacs-nox
+
+      - name: 确保 repo 干净并配置 git 身份
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git clean -fd
+          git checkout -- .
+
+      - name: 执行 auto_publish.el 构建博客
+        run: emacs --batch -l auto_publish.el
+
+      - name: 推送 HTML 到 master 分支
+        run: |
+          cd "$STORE_DIR"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --staged --quiet || git commit -m "auto publish: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          git push origin master
+#+end_src
+
+两个 Job 并行运行，互不影响。
+
+** 第三步：踩过的坑
+
+整个过程踩了不少坑，记录一下：
+
+*** 坑1：EGO 缺少依赖
+
+~auto_publish.el~ 在本地运行时，~ht~ 和 ~dash~ 两个包早就安装过了。但 CI 是全新环境，~package-install~ 列表里没有它们，导致 EGO 加载失败：
+
+#+begin_quote
+Cannot open load file: No such file or directory, ht
+#+end_quote
+
+解决：在 ~package-install~ 列表中加上 ~ht~ 和 ~dash~。
+
+*** 坑2：本地包在 CI 中不存在
+
+~toutiao~ 和 ~csdn-publish~ 是我本地的自定义包，不在任何包管理器上。CI 里根本没有：
+
+#+begin_quote
+Cannot open load file: No such file or directory, toutiao
+#+end_quote
+
+解决：用 ~(require 'toutiao nil t)~ 的 ~noerror~ 模式，找不到就静默跳过。后来发现本机上这两个包也早已不用了，干脆直接删除了相关代码。
+
+*** 坑3：括号不匹配
+
+删代码时一不小心把 ~let*~ 的关闭括号也删了，导致 Emacs 解析到文件末尾时报错：
+
+#+begin_quote
+End of file during parsing: auto_publish.el
+#+end_quote
+
+解决：补回括号，并用 ~emacs --batch --eval '(check-parens)'~ 验证。
+
+*** 坑4：EGO 内部 git commit 缺少身份
+
+EGO 构建完后会用 ~vc-git-commit~ 提交 store-dir 的变更，但 store-dir 里没配 git user：
+
+#+begin_quote
+Failed (status 128): git --no-pager commit -m Update published html files...
+#+end_quote
+
+解决：clone master 分支后立即配置 ~git config user.name/email~。
+
+*** 坑5：EGO 的 stash/pop 在 CI 中失败
+
+这是最难搞的一个。EGO 检测到 repo 有未提交变更时，会先 ~git stash~，构建完成后再 ~git stash pop~。但在 CI 中 stash pop 总是失败：
+
+#+begin_quote
+Failed (status 1): git --no-pager stash pop -q 0 .
+#+end_quote
+
+试了 ~git clean -fd~、~git checkout -- .~ 确保构建前 repo 干净，都没用——EGO 内部还是会触发 stash。
+
+最终解决方案：用 ~ego-do-publication~ 的 ~checkin-all~ 参数（第四个参数），让 EGO 用 ~git commit~ 代替 ~git stash~，从根本上避免 stash/pop：
+
+#+begin_src emacs-lisp
+;; 之前：(ego-do-publication "blog" nil nil nil)
+;; 之后：(ego-do-publication "blog" t nil "CI auto publish")
+#+end_src
+
+第二个参数 ~t~ 表示全量构建，第四个参数非 nil 时 EGO 会 commit 而不是 stash。
+
+* 总结
+
+整个折腾过程的核心就是让 ~auto_publish.el~ 在 CI 环境和本地环境都能正常运行。关键改动：
+
+1. 路径可配置化（环境变量 + 默认值）
+2. 删除废弃的第三方发布代码
+3. 补全缺失的依赖包
+4. 用 ~checkin-all~ 绕过 stash/pop 兼容性问题
+
+虽然中间踩了不少坑，但最终效果还是很满意的——以后 push 博客源文件就能自动构建发布，再也不用手动跑 ~auto_publish.el~ 了。