AlpacaNotes

AlpacaNotes博客 集成 Telegram 自动推送实战

2026-01-24

为了方便读者及时获取更新，我为 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 文件，在部署流程中加入通知步骤：

- 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 中进行特别配置：

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/" : "",
};

此外，部署工作流使用了 peaceiris/actions-gh-pages Action，它会将 out 目录（Next.js output: 'export' 的产物）自动发布到 gh-pages 分支。

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. 编写提取规则。本项目使用的规则如下（已保存为 instant-view-rules.txt）：
~version: "2.1"

# 1. Content Body
body: //article

# 2. Title
title: //h1

# 3. Subtitle (Articles only)
subtitle: //article//header//p[contains(@class, "text-xl")]

# 4. Published Date (Articles: Header / Notes: Footer)
published_date: //header//div[contains(@class, "text-sm")] | //div[contains(@class, "mt-4") and contains(@class, "text-sm")]

# 5. Cleanup
# Fix: <img> inside <p> is not allowed
@split_parent: //p/img
@remove: //div[contains(@class, "mt-16")]/a[contains(@href, "/articles")]/..
  1. 点击 Mark as Published，你将获得一个 rhash（一串哈希值，例如 d41d8cd98f00b204e980）。

7.2 配置 GitHub Secrets

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

7.3 脚本支持

我们采用了 Telegram Bot API 新版功能 link_preview_options 来完美解决兼容性问题：

  1. 显式指定预览链接：我们在 API 调用中明确告诉 Telegram 使用 Instant View 链接 (t.me/iv?...) 来生成预览卡片。
  2. 保留正文原始链接：消息正文中的 [Read More] 保持指向博客原始网址。

效果：

  • App 端：用户看到的是带有 Instant View 按钮的卡片，点击即开。
  • Web 端：预览卡片可能不显示或显示为普通链接，但用户点击正文链接时，会直接跳转博客原站，不会出现无法打开的情况。

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

← Back to Articles