许多Telegram用户希望利用官方API实现自动化功能，例如监控GitHub仓库的更新、自动编译APK并推送通知。但新手常遇到的问题包括：如何获取API凭证、如何配置GitHub Actions与Telegram Bot联动、以及如何确保APK文件正确上传。本文将手把手教你完成从环境准备到自动通知的全流程。

问题现象描述

当你尝试将Telegram Bot与GitHub仓库结合，实现代码推送后自动编译APK并发送到Telegram时，可能会遇到以下情况：Bot无法接收到GitHub的Webhook通知、APK构建失败但Bot不报错、或者文件上传后Telegram显示“文件已过期”。这些问题的根源在于API调用方式错误、GitHub Actions配置遗漏或Telegram Bot权限不足。下面将逐一解决。

准备条件：注册Telegram Bot并获取API Token

具体操作说明：

1. 打开Telegram，搜索并进入BotFather（官方机器人管理账号）。

2. 发送 /newbot命令，按提示输入机器人名称（如 MyAPKBot）和用户名（必须以 bot结尾，例如 MyAPKBot_bot）。

3. 创建成功后，BotFather会返回一个API Token，格式如 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。请立即复制并安全保存。

4. 将Bot添加到你想要接收通知的群组或频道中，并获取该群组的Chat ID（可通过发送消息后访问 https://api.telegram.org/bot<你的Token>/getUpdates查看）。

注意事项/小提示：

  • 不要将Token泄露到公开代码仓库，建议使用GitHub Secrets存储。
  • 获取Chat ID时，需要先向群组发送一条任意消息，再访问API接口。
  • 如果使用频道，Chat ID通常以 -100开头。

备用方案：

  • 若无法访问BotFather，可尝试通过代理或更换网络环境。
  • 如果忘记Token，可以在BotFather中向你的Bot发送 /token命令重新生成。

步骤：在GitHub仓库中配置Actions工作流

具体操作说明：

1. 在你的GitHub仓库根目录下创建文件夹 .github/workflows（如果不存在）。

2. 在该文件夹内新建一个YAML文件，例如 build-apk.yml。

3. 写入以下基础配置（以Android APK构建为例）：

`yaml

name: Build APK and Notify Telegram

on:

push:

branches: [ main ]

jobs:

build:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v3

- name: Set up JDK 17

uses: actions/setup-java@v3

with:

java-version: '17'

- name: Build APK

run: ./gradlew assembleRelease

- name: Upload APK as artifact

uses: actions/upload-artifact@v3

with:

name: app-release.apk

path: app/build/outputs/apk/release/app-release.apk

`

4. 保存并提交到仓库的main分支，触发首次自动构建。

注意事项/小提示：

  • 确保仓库中已有 gradlew文件和 build.gradle配置，否则构建会失败。
  • 若使用Android项目，需在 build.gradle中配置签名信息，否则生成的是未签名APK。
  • 工作流名称和触发分支可根据实际需求修改。

备用方案：

  • 如果项目不需要构建，仅监控文件变化，可移除构建步骤，直接使用 actions/upload-artifact上传其他文件。
  • 对于iOS项目，需使用macOS运行器，并配置相应的证书。

步骤：通过GitHub Actions发送消息到Telegram

具体操作说明：

1. 在GitHub仓库的 Settings → Secrets and variables → Actions中，点击 New repository secret。

2. 添加两个Secret：

- 名称 TELEGRAM_BOT_TOKEN，值填入之前获取的Bot Token。

- 名称 TELEGRAM_CHAT_ID，值填入群组或频道的Chat ID。

3. 回到 build-apk.yml文件，在构建步骤之后添加发送通知步骤：

`yaml

- name: Send Telegram Notification

if: success()

run: |

curl -s -X POST "https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN}}/sendMessage" \

-d chat_id="${{ secrets.TELEGRAM_CHAT_ID}}" \

-d text="✅ APK构建成功！仓库: ${{ github.repository}}，提交: ${{ github.sha}}"

`

4. 保存并推送更改，再次触发工作流，观察Telegram是否收到消息。

注意事项/小提示：

  • 使用 if: success()确保仅在构建成功时发送通知，失败时可添加 if: failure()分支发送错误信息。
  • sendMessage接口的 text参数支持Markdown格式，可添加链接和表情符号。
  • 消息内容可引用 github上下文变量，如 github.actor（触发用户）、github.ref（分支名）。

备用方案：

  • 如需发送文件，使用 sendDocument接口替代 sendMessage，并配合 actions/upload-artifact生成下载链接。
  • 如果不想使用curl，可安装第三方Action如 appleboy/telegram-action，但建议直接使用API以保持灵活性。

步骤：上传APK文件到Telegram并处理文件过期问题

具体操作说明：

1. 在构建步骤后，添加一个上传APK到Telegram的步骤：

`yaml

- name: Upload APK to Telegram

if: success()

run: |

# 找到构建生成的APK文件路径

APK_PATH="app/build/outputs/apk/release/app-release.apk"

# 使用sendDocument接口上传

curl -F "chat_id=${{ secrets.TELEGRAM_CHAT_ID}}" \

-F "document=@$APK_PATH" \

"https://api.telegram.org/bot${{ secrets.TELEGRAM_BOT_TOKEN}}/sendDocument"

`

2. 如果APK文件较大（超过50MB），Telegram免费版无法直接上传。此时需要分片上传或使用文件托管服务。

3. 在发送文档后，可附加一条消息说明文件有效期（Telegram服务器上的文件通常长期有效，但客户端缓存可能有限制）。

注意事项/小提示：

  • 确保 APK_PATH与构建步骤中生成的文件路径一致，可通过 ls -R app/build/outputs/调试路径。
  • 文件大小限制：免费Bot上传文件最大为50MB，超过需使用 sendMediaGroup分片或使用GitHub Release。
  • 为避免文件被覆盖，建议在文件名中加入版本号或构建时间戳。

备用方案：

  • 如果文件过大，可先将APK上传到GitHub Release，再发送Release链接到Telegram。
  • 使用 actions/upload-release-asset自动创建Release并上传APK，然后通过Telegram发送Release页面URL。

验证结果：检查工作流日志与Telegram消息

具体操作说明：

1. 在GitHub仓库页面点击 Actions标签，找到最近触发的工作流运行记录。

2. 点击运行记录，展开各个步骤查看日志。重点关注 Build APK步骤是否报错，以及 Upload APK to Telegram步骤的curl返回结果。

3. 如果返回 {"ok":true,"result":{"message_id":xxx}}，说明上传成功。返回 {"ok":false,"description":"..."}则根据错误信息排查（如Chat ID错误、Token无效）。

4. 打开Telegram目标群组或频道，确认是否收到APK文件和通知消息。点击文件应能正常下载。

注意事项/小提示：

  • 工作流日志中可能包含Token信息，但GitHub会自动隐藏Secrets值，显示为 ***。
  • 如果文件上传成功但Telegram显示“文件已过期”，可能是客户端缓存问题，重新进入聊天界面即可。
  • 建议在测试阶段使用私密群组，避免通知骚扰他人。

备用方案：

  • 如果工作流失败但本地构建正常，检查 gradlew权限：在构建步骤前添加 chmod +x gradlew。
  • 若curl请求超时，可在命令中添加 --connect-timeout 10 --max-time 30参数。

常见问题补充

Q：Telegram Bot无法收到GitHub的Webhook通知？

A：请确认已在GitHub仓库的 Settings → Webhooks中添加了正确的Payload URL（通常指向你的服务器或第三方服务）。如果使用GitHub Actions自带的触发机制，则无需额外配置Webhook，只需确保Actions工作流正确触发。

Q：APK构建成功但Telegram上传失败，提示“Bad Request: file is too big”？

A：Telegram Bot API对文件大小有限制（免费Bot最大50MB）。解决方案：1）使用 sendMediaGroup分片上传；2）将APK上传到GitHub Release，然后发送Release链接；3）申请Telegram Premium账户以提升文件限制（但Bot本身无此权限）。

Q：如何让Bot发送的消息包含APK的下载链接？

A：使用 sendMessage接口，在 text参数中插入Markdown格式的链接：[下载APK](https://github.com/用户名/仓库名/releases/latest/download/app-release.apk)。前提是已将APK上传到GitHub Release。

Q：多个仓库如何复用同一个Bot？

A：只需在多个仓库的Secrets中配置相同的 TELEGRAM_BOT_TOKEN，但每个仓库需要独立的 TELEGRAM_CHAT_ID（可指向不同群组或同一群组的不同话题）。

总结

通过Telegram API与GitHub Actions的深度结合，你可以实现代码推送后自动构建APK、上传文件并发送通知，整个过程无需手动干预，仅需正确配置Token、Secrets和工作流文件即可稳定运行。