为博客集成 Telegram 自动推送：GitHub Actions 与 Bot API 实战

为了方便读者及时获取更新，我为 AlpacaNotes 博客增加了 Telegram 频道自动推送功能。每当有新文章发布时，GitHub Actions 会自动触发脚本，将文章标题和链接发送到订阅频道。以下是实现这一功能的简要流程。

1. 申请 Telegram Bot

首先，你需要拥有一个 Telegram 账号并申请一个机器人：

1. 在 Telegram 中搜索 @BotFather。
2. 发送指令 /newbot 创建新机器人。
3. 按照提示设置机器人的名称（Name）和用户名（Username）。
4. 创建成功后，BotFather 会给你一个 HTTP API Token（类似 123456789:ABCdef...），请妥善保管。

2. 设置频道并获取 Chat ID

1. 创建一个新的 Telegram Channel（频道），或者使用现有频道。
2. 将你刚才创建的机器人添加为频道管理员（Administrator），赋予发送消息的权限。
3. 为了获取频道的 Chat ID，你可以先在频道里随便发一条消息，然后转发给 @getidsbot（或其他类似 ID 查询机器人），它会返回以 -100 开头的频道 ID（例如 -1003229698152）。

3. 配置 GitHub Secrets

为了安全起见，不要将 Token 直接硬编码在代码中。

1. 进入博客项目的 GitHub 仓库页面。
2. 点击 Settings -> Secrets and variables -> Actions。
3. 新建 Repository Secret：
   • TELEGRAM_TOKEN: 填入 BotFather 给你的 Token。

4. 编写自动化脚本

在项目中编写一个 Node.js 脚本（scripts/telegram-notify.js），用于检测变更并发送消息。

主要逻辑如下：

1. 使用 git diff 识别本次提交中新增的 .md 文件。
2. 解析 Markdown 文件的 Frontmatter（元数据），提取标题和描述。
3. 调用 Telegram 的 sendMessage API，将文章标题、描述和链接格式化后发送到指定频道。

5. 配置 GitHub Actions 工作流

最后，修改 .github/workflows/deploy.yml 文件，在部署流程中加入通知步骤：

1
2
3
4
5
6
7
8

- name: Check for new content and notify
  if: success()
  env:
    TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
    TELEGRAM_TO: "-1003229698152" # 你的频道 ID
    SITE_URL: "https://linguista.cn"
    BASE_PATH: "/alpacanotes"
  run: node scripts/telegram-notify.js

6. 静态站点部署配置

本博客使用 Next.js 构建，并托管在 GitHub Pages 上。为了确保静态资源加载正确（特别是当部署在子路径如 /alpacanotes 下时），需要在 next.config.ts 中进行特别配置：

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

const isProd = process.env.NODE_ENV === "production";

const nextConfig: NextConfig = {
  // 启用静态导出模式，生成纯 HTML/CSS/JS 文件
  output: isProd ? "export" : undefined,
  
  // 禁用 Next.js 自带的图片优化服务（GitHub Pages 不支持 Node.js 运行时）
  images: {
    unoptimized: true,
  },
  
  // 设置子路径，匹配 GitHub Pages 的仓库名
  basePath: isProd ? "/alpacanotes" : "",
  assetPrefix: isProd ? "/alpacanotes/" : "",
};

此外，部署工作流目前已经改为 shell 方式同步 out 目录到外部 gh-pages 分支，并显式补上 .nojekyll，以避免 GitHub Pages 忽略 _next 目录导致静态资源丢失。

7. 配置 Telegram Instant View (即时预览)

为了让用户在 Telegram 中获得更好的阅读体验（无需跳转浏览器即可秒开文章），我们配置了 Instant View。

7.1 创建 Instant View 模板

1. 登录 Telegram Instant View Editor。
2. 输入你的博客文章示例链接（例如 https://linguista.cn/alpacanotes/articles/telegram-integration）。
3. 编写提取规则。早期规则曾依赖 text-xl、mt-16 之类的样式类名，后来在实际排查中证实过于脆弱。当前更可靠的做法是让页面模板输出稳定的 data-iv-* 标记，并在同域名多模板场景下保留回退规则。核心思路如下：

1
2
3
4
5
6
7
8
9

~version: "2.1"

body: //*[@data-iv-body] | //article[contains(@class, "docs-content")]//div[contains(@class, "md-theme-amp")]
title: //*[@data-iv-title] | //article[contains(@class, "docs-content")]//div[contains(@class, "md-theme-amp")]//h1[1]
subtitle: //*[@data-iv-subtitle] | //article[contains(@class, "docs-content")]//div[contains(@class, "md-theme-amp")]//h1[1]/following-sibling::p[1]
author: //*[@data-iv-author] | //article[contains(@class, "docs-content")]//div[contains(@class, "text-muted") and contains(@class, "text-sm")][1]/span[1]
published_date: //*[@data-iv-published]/@data-iv-published | //article[contains(@class, "docs-content")]//div[contains(@class, "text-muted") and contains(@class, "text-sm")][1]/span[last()]
@split_parent: //p/img
@remove: //*[@data-iv-ignore] | //article[contains(@class, "docs-content")]//div[contains(@class, "mb-4")]

4. 点击 Mark as Published，你将获得一个 rhash（一串哈希值，例如 d41d8cd98f00b204e980）。

7.2 配置 GitHub Secrets

1. 回到 GitHub 仓库的 Settings > Secrets and variables > Actions。
2. 新建 Secret TELEGRAM_IV_RHASH，填入刚才获得的 hash 值。

7.3 脚本支持

link_preview_options 可以作为 Bot 推送中的辅助能力，但它并不是一个“填了就完美生效”的万能开关。后续排查中确认了几个更接近真实情况的结论：

1. t.me/iv?url=...&rhash=... 裸链接本身可以作为私有 Instant View 入口直接使用；
2. 通过 Bot API 指定 link_preview_options.url = t.me/iv?...，并不总能稳定复现“手动粘贴裸 IV 链接”的行为；
3. 消息结构、GitHub Pages 发布时序、Telegram 客户端缓存都会影响卡片最终是否挂上 INSTANT VIEW；
4. 更稳妥的工程做法是：先确保页面已经真正公网可抓取，再发送消息，并始终保留原始文章链接作为阅读兜底。

如果你想看这一轮排查的完整经过，可以继续阅读：

• 《为静态站点配置 Telegram Instant View：从页面标记到部署等待》（实操指南）
• 《Instant View 踩坑记：折腾了一整天，答案是「等一下」》（排查故事）

本文即为该功能的测试文章。如果你在 Telegram 频道看到了这条推送，说明自动化流程已配置成功！