Hexo 博客工程化笔记：自动部署 · SEO · 阅读量分析

Step 00 · Fit

先看清本站现状，再决定做哪些

• 源码与站点同仓库、同 main 分支：本地 hexo d（hexo-deployer-git）会把构建产物 public/ 强推到 main，远程 main 只保留“构建后的站点”，源码并不在远程 main 上备份。
• 用户主页仓库：Biko-Duckyo.github.io 这类用户主页，站点必须从默认分支 main 提供，不能像教程里那样发布到 gh-pages 分支。
• 文章量小：本站是个人小站，不必照搬“400 篇内容工厂”。优先做自动部署 + 基础 SEO，收益最高；AI 批量产文按需。

Step 01 · Deploy

GitHub Actions：push 即发布

1) 把源码迁到 hexo 分支（仅首次）

cd C:\Blog\superBrain
git checkout -b hexo
git add .
git commit -m "chore: source on hexo branch"
git push -u origin hexo

此后源码只在 hexo 分支维护；main 交给 Actions 自动发布，不再手动 hexo d。

2) 部署工作流

.github/workflows/deploy.yml

name: Deploy Hexo

on:
  push:
    branches: [hexo]

concurrency:
  group: deploy-group
  cancel-in-progress: false

permissions:
  contents: write

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: hexo

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Cache Hexo
        uses: actions/cache@v4
        with:
          path: node_modules
          key: hexo-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
          restore-keys: hexo-${{ runner.os }}-

      - name: Install
        run: npm ci

      - name: Build
        run: npx hexo clean && npx hexo generate
        env:
          NODE_ENV: production

      - name: Publish public to main
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: main
          force_orphan: true

3)（可选）发布前预检

- name: Validate HTML
  run: npx html-validate "public/**/*.html" || true

- name: Broken links
  run: |
    npx hexo server -p 4000 &
    npx broken-link-checker http://localhost:4000 --recursive --filter-level 3 || true

Step 02 · SEO

SEO 内建到写作流程

1) Frontmatter 规范

---
title: 主关键词 - 长尾描述
date: 2026-10-10 10:00:00
categories: 笔记
tags: [Hexo, GitHub Actions, SEO]
description: 一句话摘要，控制在 150 字内，包含核心关键词。
---

• title：主关键词在前；description 直接决定搜索结果摘要；tags 3–5 个；categories 唯一。

2) 结构化数据 JSON-LD

3) Sitemap

npm install hexo-generator-sitemap --save

_config.yml

sitemap:
  path: sitemap.xml
  rel: false
  tags: true
  categories: true

构建后得到 /sitemap.xml，提交到 Google Search Console / Bing Webmaster；并在 robots.txt 里加一行 Sitemap: https://biko-duckyo.github.io/sitemap.xml。

4) 内链 / 相关阅读

文末放 3 条最相关链接即可，建议折叠，避免页面过长：

<details>
<summary>相关阅读</summary>

- [文章一](链接)
- [文章二](链接)
- [文章三](链接)

</details>

Step 03 · Analytics

阅读量分析

1) 不蒜子：Butterfly 已内置

_config.butterfly.yml

busuanzi:
  site_uv: true
  site_pv: true
  page_pv: true

开启后自动显示站点 UV/PV 与文章阅读量，无需手动加脚本。加个兜底，服务慢时不一直转圈：

setTimeout(function(){
  document.querySelectorAll('#busuanzi_value_page_pv').forEach(function(el){
    if(el.textContent==='') el.textContent='暂无数据';
  });
}, 3000);

2) Umami / GA：用 Butterfly Inject 接入

_config.butterfly.yml

inject:
  head:
    - <script defer src="https://你的umami域名/script.js" data-website-id="你的id"></script>

Umami 可用其官方 Docker Compose（PostgreSQL）自托管；个人小站用不蒜子通常已够。

Step 04 · AI (optional)

AI 辅助选题（按需，不建议批量产文）

维护一个选题池 .writing-backlog.md，用待办标记状态：

# 格式：- [ ] 标题 | 搜索量(高/中/低) | 竞争度 | 优先级
- [ ] 某主题实战 | 搜索量:中 | 竞争度:低 | P0
- [x] 已完成的选题

• P0：搜索量中/低 + 竞争度低 = 蓝海词，优先写。
• P1：搜索量高 + 竞争度高 = 需差异化角度。

Step 05 · Pitfalls

踩坑记录

• 构建慢/超时：加 node_modules 缓存；文章多时用 timeout 300 npx hexo generate --bail 快速失败。本站体量一般无需增量构建。
• AI 生成的 frontmatter 不一致：缺引号、日期格式乱、tags 写成字符串。提交前用脚本校验（必填 title/date/categories/tags/description，并把 tags/categories 统一成数组）。
• 内链让文章过长：只放 3 条并用 <details> 折叠。
• 不蒜子偶发不稳定：加 3 秒兜底显示“暂无数据”。
• 别再手动 hexo d：切到 Actions 后，本地强推 main 会与自动部署互相覆盖；统一由 hexo 分支触发。