hexo-bb-channel

English | 简体中文

将公开 Telegram Channel 渲染成 Hexo 博客里的动态碎片流页面。

hexo-bb-channel 是一个轻量 Hexo 插件：它只生成 /bb/ 页面壳，内容在浏览器端从独立 API 拉取。这样博客仍然是静态站，但 Telegram Channel 更新后不需要重新 hexo generate。

效果预览

在线示例：https://www.kaaaaai.cn/bb/

为什么这样设计

• 主题无关：通过 Hexo generator 输出页面，NexT、Wizarding 以及大部分主题都可以接入。
• 静态博客里的动态内容：页面访问时从 API 拉取 Telegram 内容。
• 博客侧不放 Telegram 凭证：Hexo 只需要配置一个 API 地址。
• 适合碎片流展示：支持正文、Telegram 原生 hashtag entity、图片、文件、分页、图片预览交互。
• 保留主题评论能力：生成的是标准 Hexo page，并设置 comments: true；最终是否显示评论取决于主题和评论系统。

快速开始

1. 先部署 API

先创建一个公开 Telegram Channel。公开链接应该类似 https://t.me/my_notes，API 里的 TG_CHANNEL 只填写 my_notes，不要带 @。

先部署配套 API：

后端仓库：Kaaaaai/kaaaaai.tools.channel-api 详细的 Telegram 频道创建步骤见 API 仓库 README。

生产环境请将 ALLOWED_ORIGINS 设置为博客的完整 Origin，例如 https://www.example.com，确保生成页面能够请求 API。

2. 安装 Hexo 插件

从 npm 安装最新稳定版：

npm install hexo-bb-channel

如需试用 GitHub 默认分支上尚未发布的改动，可改为：

npm install github:Kaaaaai/kaaaaai.tools.hexo-bb-channel

安装 Hexo 插件不会自动部署配套 API。请先完成第 1 步，并保留站点根目录 _config.yml 中的 bb_channel 配置。

3. 配置 Hexo

在 Hexo 主目录的 _config.yml 增加：

bb_channel:
  enable: true
  mode: client
  route: bb/
  title: 闲言碎语
  description: 这些片段可能来自于大脑皮层短暂兴奋后的捕捉 🤏
  api_base: https://your-channel-api.vercel.app
  page_size: 20

然后重新生成：

hexo clean
hexo generate
hexo server

打开：

http://localhost:4000/bb/

配置项

| 配置 | 默认值 | 说明 | | --- | --- | --- | | enable | true | 是否启用页面。 | | mode | client | 当前支持客户端动态渲染。 | | route | bb/ | 页面路由，例如 moments/。 | | title | moments | 页面内容区标题。 | | description | 空 | 页面描述。 | | api_base | 空 | client 模式必填。kaaaaai.tools.channel-api 的 API 根地址；未配置时页面会显示 Missing bb_channel.api_base。 | | page_size | 20 | 每页拉取数量。 |

工作原理

Hexo build
  └─ hexo-bb-channel 生成 /bb/index.html

Browser
  └─ 请求 api_base/api/posts?page=1&page_size=20

kaaaaai.tools.channel-api
  ├─ 抓取公开 Telegram Channel 页面
  ├─ 解析消息、标签、图片、文件
  └─ 将标准化数据缓存到 Upstash Redis

Hexo 构建阶段不会抓取 Telegram，只生成页面壳。实际内容在访问页面时由 API 返回。

主题接入说明

插件通过 Hexo generator 输出页面，理论上不需要修改主题模板。已在以下场景使用：

• NexT theme
• Wizarding theme
• 任何能渲染标准 Hexo page layout 的主题

如果你的 source/ 或主题里已经存在 /bb/ 页面，请删除旧页面，或修改 bb_channel.route 避免重复输出。

页面能力

• 客户端分页
• 每条消息保留 Telegram 原文链接
• 基于 Telegram 原生 entity 提取 hashtag，而不是宽松正则匹配
• 图片缩略图和点击展开预览
• 多图横向轮播
• 文件附件卡片
• 兼容 Hexo 图片懒加载插件的图片延迟注入
• 支持浏览器前进、后退的可分享深链

深链

URL 同时提供页码和卡片 ID，即可直达异步渲染后的 BB：

/bb/?page=2#bb-123

插件会先加载第 2 页，再滚动到 bb-123，并短暂复用当前卡片选中效果。分页会同步更新 ?page=N、清除旧的 BB hash，并支持浏览器前进和后退。如果目标 ID 不在指定页，页面仍可正常使用，插件不会自动遍历其他分页。

API 返回结构

插件期望 API 返回：

GET /api/posts?page=1&page_size=20

{
  "channel": {
    "title": "Channel title",
    "description": "Channel description"
  },
  "posts": [
    {
      "id": "101",
      "datetime": "2026-01-01T12:00:00.000Z",
      "html": "<p>Hello</p>",
      "tags": ["Tools"],
      "media": [{ "type": "image", "src": "https://..." }],
      "attachments": [{ "title": "file.dmg", "meta": "351.5 MB", "url": "https://..." }],
      "source": { "telegramUrl": "https://t.me/channel/101" }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 3,
    "totalItems": 60,
    "hasNext": true,
    "hasPrev": false
  }
}

FAQ

Telegram 更新后需要重新构建博客吗？

不需要。页面壳是静态的，但内容由 API 动态返回。

支持私有 Telegram Channel 吗？

不支持。当前方案面向 t.me/s/<channel> 可访问的公开频道。

为什么需要独立 API？

静态站不适合保存刷新密钥或 Redis 凭证。独立 API 可以把抓取、缓存、CORS、刷新逻辑从博客里隔离出来。

可以用于非 Hexo 博客吗？

当前前端封装为 Hexo 插件；后端 API 是通用 JSON 服务，其他静态站也可以消费同一份数据。

开发

npm install
npm test

相关项目

• API 后端：Kaaaaai/kaaaaai.tools.channel-api

License

MIT