Hexo 接入 AI 摘要

我这次给自己的 Hexo 博客加 AI 摘要，最后能稳定跑起来，核心不是“主题对不对”，而是三件事：

1. 摘要在什么阶段生成
2. API 配置放哪里
3. Fluid 主题怎么把摘要显示出来

这篇就只讲这三件事，按实际落地顺序写，尽量让你看完能直接照着做。

一、我最后采用的方案

我现在这套方案是：

• 用 hexo-ai-summary-liushen 在构建阶段生成摘要
• 用单独的 ai-summary.local.yml 放 API、Token、Model
• 用 layout-inject 给 Fluid 文章页插入摘要模块
• 用自定义 CSS 和 JS 负责样式和打字机效果

这套方案的关键点只有一句话：

摘要在构建时生成，页面只负责显示。

这样做的好处很直接：

• 不需要让前端直接请求 AI
• 生成后的博客还是静态页面，部署简单
• 不会把 Key 暴露到浏览器端

二、先装插件

先装依赖：

1

npm install hexo-ai-summary-liushen

装完以后，先别急着改主题。第一步应该先让“摘要生成”本身跑通。

三、在 _config.yml 里写基础配置

我的主配置现在是这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

aisummary:
  enable: false
  cover_all: false
  summary_field: summary
  logger: 1
  api: https://api.openai.com/v1/chat/completions
  token: ''
  model: ''
  prompt: >
    你是个人博客的 AI 摘要生成工具，只根据文章正文生成一段中文摘要。
    请使用简体中文，输出单行纯文本，长度控制在180到280字之间。
    摘要开头固定为“这里是远枫AI，这篇文章”，后面紧接自然续写，不要换行。
    摘要风格参考中文技术博客里的 AI 导读，要把文章的主题、场景、核心做法、关键结论尽量讲清楚，允许信息密度高一些，读起来像一段完整的内容导览。
    如果是教程或部署类文章，要尽量交代它解决了什么问题、用了什么方案、提供了哪些关键步骤或配置。
    如果是经验、思考或观点类文章，要尽量交代作者关注的问题、核心判断、适用场景或实践建议。
    禁止输出与摘要无关的内容，禁止分点、禁止列小标题、禁止使用 Markdown、禁止输出换行。
  ignoreRules:
  max_output_token: 2000
  concurrency: 2

这里几个关键项：

• summary_field 保持成 summary
• cover_all: false 表示只给没有摘要的文章生成
• prompt 最好自己改，不然生成味道会很重

四、不要把 API 写死在主配置里

我不建议把这些直接写进仓库里的 _config.yml：

• 接口地址
• API Key
• 模型名

更稳的方式是单独建一个本地文件 ai-summary.local.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13

aisummary:
  enable: true
  api: https://your-api-base/v1/chat/completions
  token: sk-xxxx
  model: your-model
  cover_all: false
  summary_field: summary
  logger: 1
  max_output_token: 2000
  concurrency: 2

ai_summary:
  model_name: Your-Model-Name

这样做有几个好处：

• 改模型方便
• 换 Key 不用改主配置
• 仓库不会带出敏感信息

记得把这个文件加入 .gitignore。

五、给构建命令单独分流

普通构建还是照常用：

1
2
3

hexo g
hexo s
hexo cl

但如果要生成 AI 摘要，建议在 package.json 里单独加这两条：

1
2
3
4
5
6
7

{
  "scripts": {
    "build": "hexo generate",
    "build:ai": "hexo clean --config _config.yml,ai-summary.local.yml && hexo generate --config _config.yml,ai-summary.local.yml",
    "clean:ai": "hexo clean --config _config.yml,ai-summary.local.yml"
  }
}

这里我特意把 build:ai 写成了“先 clean 再 generate”，这个不是多余，而是我这次真实踩到的坑。

为什么 build:ai 不能只写 hexo generate

我这次新文章就是这样出问题的。

新文章先通过普通构建生成过一次之后，页面已经存在，但没有 AI 摘要。
这时候如果再跑一个不带 clean 的：

1

npm run build:ai

Hexo 可能因为缓存和数据库状态，不会重新渲染那篇文章。结果就是：

• 页面还在
• 插件没有报错
• 但这篇文章根本没进入 AI 摘要处理流程

我实际检查时，build:ai 就出现了 0 files generated，所以新文章当然不会补上摘要。

后来我一跑清理再生成，日志里立刻出现了：

1

[Hexo-AI-Summary-LiuShen] 摘要 Hexo 接入 AI 摘要 完成

所以这里的结论很明确：

如果你希望 build:ai 稳定给新文章或刚修改过的文章补摘要，就应该让它先 clean。

六、Fluid 主题下怎么显示摘要

插件只负责一件事：把摘要写进文章 front matter 的 summary 字段。

它不会自动帮你在页面里显示。

所以在 Fluid 下还需要补一层展示逻辑。我这次没有直接改主题源码，而是用了更稳的做法：

• scripts/ai-summary-inject.js
• layout-inject/post/ai-summary.ejs
• source/css/ai-summary.css
• source/js/ai-summary.js

流程其实很简单：

1. 文章页渲染时读取 page.summary
2. 如果有摘要，就在正文前插入一个 AI 摘要模块
3. 前端脚本只负责打字机显示

这样以后升级 hexo-theme-fluid，也不用重新去改主题包里的文件。

七、为什么别人看起来像“流式输出”

这个点我后面也确认过。

你现在页面上看到的“逐字出现”，并不是真的前端又去请求了一次 AI。它只是把已经生成好的摘要，用 JS 按字打出来。

所以真实流程其实是：

1. 构建时调用 AI
2. 把结果写到文章 summary
3. 页面加载后再做打字机展示

这种方式更适合博客，因为：

• 没有访客侧 API 调用
• 不会暴露 Key
• 页面仍然可以静态部署

八、我这次遇到的两个坑

1. Windows 路径兼容

插件原始逻辑里会判断：

1

data.source.startsWith('_posts/')

但 Windows 下文章路径可能是反斜杠，所以我额外加了一个兼容脚本，把路径统一成斜杠形式后再交给插件处理。

2. build:ai 不重渲染新文章

这个就是上面说的缓存问题。

如果新文章已经先被普通构建过一次，再直接跑不带 clean 的 build:ai，它可能根本不会重新走摘要生成。

这个问题不是 API 失败，也不是 Prompt 有问题，而是文章没有重新进入插件处理链路。

九、我现在这套 AI 摘要有没有明显问题

我刚刚顺手把当前这套链路也检查了一遍，结论是：

• 插件本身能正常工作
• Fluid 主题的摘要展示也正常
• 新文章没有摘要的原因，不是插件坏了
• 真正的问题是原来的 build:ai 命令不够稳

也就是说，你现在这套 AI 摘要功能本身没坏，核心问题是命令设计。

我已经把命令改成下面这个更稳的形式了：

1
2

"build:ai": "hexo clean --config _config.yml,ai-summary.local.yml && hexo generate --config _config.yml,ai-summary.local.yml",
"clean:ai": "hexo clean --config _config.yml,ai-summary.local.yml"

以后可以直接这样记：

• 普通生成：npm run build
• 生成并补 AI 摘要：npm run build:ai
• 清缓存：npm run clean
• 清 AI 构建缓存：npm run clean:ai

十、最短可执行步骤

如果你只想快速照着做，流程就是下面这几步：

1. 安装 hexo-ai-summary-liushen
2. 在 _config.yml 里写 aisummary 基础配置和 Prompt
3. 新建 ai-summary.local.yml，把 API、Token、Model 放进去
4. 给 Fluid 文章页加 layout-inject 的摘要模板
5. 加上自定义 CSS 和 JS，做样式和打字机效果
6. 用 npm run build:ai 生成
7. 如果发现新文章没摘要，先检查构建日志里有没有 摘要 xxx 完成

如果这条日志没有出现，就不要先怀疑主题，先怀疑这篇文章根本没进入插件处理流程。

十一、总结

对 Hexo + Fluid 来说，我现在最推荐的方式就是：

• 摘要放在构建期生成
• API 放本地私有配置
• 主题展示用注入，不直接改主题源码
• build:ai 一定要带 clean

这样整套东西会稳定很多，也更符合静态博客的使用方式。