我的博客新文章是怎么通知到 QQ 群的：GitHub Actions 与 NapCat 工作流程

早风依旧

正在加载歌曲信息……

私有音源

0:00 0:00

这篇文章专门记录博客的新文章 QQ 群通知系统。

它和 AI 摘要是两套独立工作流：

AI 摘要负责生成摘要、更新 deploy、触发网站部署
QQ 群通知负责检测 main 中新增的文章，并在文章真正上线后发送通知

这篇只记录 QQ 群通知部分，方便以后回顾配置、排查消息未发送、链接不正确或部署等待超时等问题。

什么情况下会触发通知

QQ 通知工作流只监听：

main 分支

并且只关心：

1 2	source/_posts/.md source/_posts//.md

因此：

main 新增文章
→ 触发通知工作流

main 修改旧文章
→ 不作为新文章通知

deploy 更新
→ 不触发通知

AI 摘要缓存更新
→ 不触发通知

只修改 CSS、主题或配置
→ 不触发新文章通知

工作流只筛选 Git 状态为：

也就是新增文件。

这样可以防止：

修改旧文章时重复通知
AI 摘要更新时重复通知
deploy 分支自动同步时重复通知
Cloudflare 重新部署时重复通知

完整通知流程

当我发布一篇新文章时，整体过程如下：

本地创建 Markdown 文章
    ↓
提交并推送到 main
    ↓
GitHub Actions 检测到新增文章
    ↓
读取文章 Front Matter
    ↓
判断是否允许发送通知
    ↓
等待文章出现在 atom.xml
    ↓
从 RSS 中读取真实文章地址
    ↓
调用 NapCat Webhook
    ↓
向指定 QQ 群发送消息

需要注意的是，QQ 通知工作流和 AI 摘要工作流会同时启动。

网站现在实际部署的是：

deploy

因此文章推送到 main 后，不会立刻出现在正式网站。

中间还要经过：

main
→ AI 摘要工作流
→ deploy
→ Cloudflare 构建
→ 正式网站更新

所以通知脚本不能一开始就直接发送消息。

为什么要等待 atom.xml

如果在文章刚推送到 main 时立刻发群通知，可能出现：

1
2
3

群消息已经发出
但 Cloudflare 还没有完成部署
用户点击链接后文章不存在

为避免这个问题，通知脚本会检查：

1	https://blog.mcpq.cc/atom.xml

它不会自己猜测文章地址，而是等待新文章真正出现在 RSS 中。

检查规则：

1
2
3

每 10 秒检查一次
最多检查 30 次
总等待时间最多 5 分钟

只有在 Atom RSS 中找到标题完全匹配的文章后，才读取真实文章链接并发送通知。

这样可以保证：

1 2	通知发出时文章通常已经真正上线

为什么从 RSS 读取文章地址

博客文章地址可能受到以下配置影响：

permalink
slug
Hexo 路由规则
中文文件名
自定义文章链接

如果通知脚本只根据日期和文件名拼接地址，容易生成错误链接。

所以现在的做法是：

等待 atom.xml 更新
→ 根据文章标题找到对应 entry
→ 读取 rel="alternate" 的链接
→ 把这个地址放进 QQ 消息

这样最终发送的是 Hexo 实际生成的文章地址。

文章 Front Matter 中的通知配置

新文章常用配置：

---
title: 文章标题
date: 2026-07-26 00:00:00
updated: 2026-07-26 00:00:00
permalink: /posts/article-slug/
notify: true
excerpt: 用于首页、RSS 和 QQ 群通知的摘要。
description: 用于搜索引擎的页面描述。
cover:
tags:
  - 标签一
categories:
  - 杂乱的知识
---

允许发送 QQ 群通知

1	notify: true

或者不写 notify，默认同样会发送。

关闭 QQ 群通知

1	notify: false

下面这些值也会被识别为关闭：

1
2
3

no
off
0

适合：

测试文章
不想打扰群成员的记录
私密内容
仅供自己查看的说明文章

不发布的文章

如果文章设置：

1	published: false

通知脚本会直接跳过。

QQ 消息中的摘要来自哪里

QQ 消息中的“摘要”和文章页面里的 AI 摘要不是同一个东西。

QQ 通知摘要优先读取：

excerpt:

其次读取：

1	description:

如果这两个字段都没有，就从正文中清理 Markdown 后截取一段。

优先级：

excerpt
    ↓
description
    ↓
正文

因此新文章最好主动填写：

1 2	excerpt: 适合发到 QQ 群里的简短说明。 description: 适合搜索引擎使用的页面描述。

QQ 通知目前不会直接读取：

1	source/_data/ai-summaries.json

也不会等待 AI 摘要文本后再把 AI 摘要发送到群里。

最终发送的消息格式

消息大致如下：

📢 新文章发布

标题：文章标题

摘要：文章的 excerpt、description 或正文节选

阅读全文：https://blog.mcpq.cc/posts/...

📝 文章已更新

但当前 GitHub Actions 只筛选新增文章，因此正常自动流程只发送：

📢 新文章发布

NapCat 请求过程

通知脚本会向：

1	NAPCAT_WEBHOOK_URL

发送一个 JSON 请求，核心内容类似：

{
  "group_id": "目标群号",
  "message": "新文章通知内容"
}

脚本会检查：

HTTP 状态码
返回内容是否为 JSON
status 是否为 ok
retcode 是否为 0

成功时日志显示：

1 2	QQ 群通知发送成功：文章标题文章地址：https://...

失败时会显示 NapCat 返回的错误内容。

手动测试 QQ 群通知

进入：

GitHub
→ zqf-blog
→ Actions
→ 新文章通知到 QQ 群
→ Run workflow

手动运行时需要填写：

1	source/_posts/文章文件名.md

例如：

1	source/_posts/我的测试文章.md

手动测试会把指定文章当作新增文章处理。

需要注意：

文章文件必须存在
notify 不能是 false
published 不能是 false
正式网站的 atom.xml 中必须能找到同标题文章
否则最多等待 5 分钟后失败

QQ 通知和 deploy 分支的关系

QQ 通知工作流监听：

main

Cloudflare 实际部署：

deploy

两个流程同时开始：

main 推送新文章
    ↓
┌────────────────────────────┬────────────────────────────┐
│ AI 摘要工作流               │ QQ 通知工作流               │
│                            │                            │
│ 生成摘要                   │ 检测新增文章                │
│ 更新 deploy                │ 等待 atom.xml              │
│ 触发 Cloudflare 部署        │ 部署完成后发送消息           │
└────────────────────────────┴────────────────────────────┘

QQ 工作流虽然不直接监听 deploy，但它通过不断读取正式网站的 atom.xml，间接等待 deploy 完成部署。

这能避免 deploy 的机器人提交再次触发 QQ 通知。

总结

当前 QQ 群通知系统可以概括为：

1
2
3

main 负责触发
atom.xml 负责确认文章已经上线
NapCat 负责发送到 QQ 群

完整过程：

新增文章并推送 main
→ GitHub Actions 检测新文件
→ 等待正式网站 RSS 更新
→ 获取真实文章链接
→ 通过 NapCat 发送 QQ 群通知

它和 AI 摘要、deploy 部署是相互配合但彼此独立的两套工作流。