Telegram Serverless — 无需服务器，直接运行你的 Bot 后端

写在前面

做一个 Telegram Bot 一直有个绕不开的坎：你得找一个地方跑它。

过去的选择也没几个——租一台 VPS、挂一个云函数、或者塞到某个永远不关机的树莓派上。然后你还要配域名、配 SSL、配 Webhook、写健康检查、盯着监控面板……而这一切只是为了响应一个 /start 命令。

2026 年，Telegram 官方出手了。他们推出了 Telegram Serverless——一个让你直接在 Telegram 的基础设施上运行 Bot 和 Mini App 后端的平台。没有服务器，没有容器，不用考虑扩容。

什么是 Telegram Serverless

一句话：你在本地写 JavaScript 模块，用一条命令部署上去，Telegram 用 V8 沙箱帮你跑——这个沙箱就放在 Bot API 旁边，还有一个内置的 SQLite 数据库。

整个架构就三个组件：

• handlers/ —— 入口文件，一个文件对应一个 Telegram 更新类型（消息、回调查询、内联查询等）
• lib/ —— 共享代码，随便 import
• schema.js —— 数据库表定义

当一条更新过来——用户发了个消息、点了个按钮、发起了一个内联查询——Telegram 自动路由到对应的 handler，调用它的默认导出函数。这个函数通过 SDK 操作 Bot API 和数据库，返回结果。就这样。

没有匹配 handler 的更新类型直接被忽略，所以你只需要加真正用得到的 handler。

为什么这玩意值得关注

1. 零基础设施

没有机器要租、没有补丁要打、没有监控要配。代码按需执行，随 Bot 的用户量自动伸缩。如果你只是为了个人或小团队用 Bot，这是巨大的解脱。

2. 开箱即用

Bot API、数据库、HTTP 请求——全内置。不需要装任何 npm 包，不需要配任何环境变量。import 进来就能用。

3. 正经的开发工作流

项目在本地文件夹里，用 Git 管理。你编辑文件、查看差异、原子化部署、用审查过的迁移来管理数据库 schema。这就是你已经在做的那些事，只是现在不用写服务器代码了。

4. 快

V8 沙箱就在 Telegram 自己的系统旁边，调用 Bot API 和数据库的延迟极低。你不会再有因为服务器在另一个大洲而产生的几百毫秒延迟。

快速上手

第一步：在 BotFather 里开启 Serverless

打开 @BotFather → 找到你的 Bot → Serverless → 打开开关。这一步会在 Bot 上启用 Serverless 功能，同时解锁 CLI Access Token、handlers、library 和数据库。

第二步：创建项目

npm create @tgcloud/bot example_bot
cd example_bot

这会帮你搭好一个可直接编辑的项目结构：

example_bot/
├─ docs/
│  └─ tgcloud-sdk.md
├─ handlers/
│  └─ message.js
├─ lib/
├─ AGENTS.md
├─ package.json
└─ schema.js

第三步：绑定 Bot

npx tgcloud login

输入从 @BotFather 拿到的 CLI Access Token（注意：这不是 Bot API Token，是另一个单独的 token，格式是 app<id>:<secret>）。

第四步：部署

npx tgcloud push

这会把你更改过的模块一次性原子化上传。然后就活了——打开 Telegram 给你的 Bot 发消息，starter handler 会直接回复你。

第五步：加数据库

编辑 schema.js，声明一个表：

import { table, integer, text, sql } from 'sdk/db';

export const messages = table('messages', {
  id:      integer('id').primaryKey({ autoIncrement: true }),
  chatId:  integer('chat_id').notNull(),
  text:    text('text'),
  created: integer('created_at', { mode: 'timestamp' }).default(sql`(unixepoch())`),
});

然后两步走：

npx tgcloud push       # 上传 schema.js
npx tgcloud migrate    # 创建 messages 表

注意：push 永远不会动你的数据库。代码部署和数据迁移是严格分开的两个步骤。

第六步：读写数据

import { api, db } from 'sdk';
import { messages } from 'schema';
import { eq } from 'sdk/db';

export default async function (message) {
  await db.insert(messages)
    .values({ chatId: message.chat.id, text: message.text })
    .run();

  const count = await db.$count(messages, eq(messages.chatId, message.chat.id));

  await api.sendMessage({
    chat_id: message.chat.id,
    text: `已保存。这个会话至今共 ${count} 条消息。`,
  });
}

第七步：不部署也能测试

npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "hello" }'

这个命令用你本地的代码在平台上执行 handler，不发布。输出 log、返回值、执行时长。这是最快的迭代循环。

数据库和迁移

Telegram Serverless 内置了一个 SQLite 数据库。定义表用的是 Drizzle 风格的 DSL，看起来像这样：

import { table, integer, text, sql } from 'sdk/db';

export const counters = table('counters', {
  chatId: integer('chat_id').primaryKey(),
  seen:   integer('seen').notNull().default(0),
});

每次 schema 变更都会经过 migrate 命令的审核。Telegram 把变更分成了几个等级：

删表或删列不是直接删除——你要在 schema 里标记为 deprecated()，然后迁移时才会以 warning 状态让你逐个确认。这种设计避免了一个误操作整库全丢的惨案。

SDK 速览

一个模块在运行时只有一个库：sdk。它把 Bot API、数据库、HTTP 请求打包在一起，不需要额外装任何东西。

import { db, api, fetch, BotApiError } from 'sdk';

Bot API

await api.sendMessage({ chat_id: id, text: 'Hello!' });
await api.editMessageText({ chat_id, message_id, text: 'Updated' });

注意：返回值已经解包了——getMe() 直接返回用户对象，而不是 { ok: true, result: ... } 这种包装。失败时抛出 BotApiError，携带 .code、.description、.method 和 .parameters。

HTTP 请求

import { fetch } from 'sdk';

const res = await fetch('https://api.example.com/users', {
  method: 'POST',
  body: fetch.body.json({ name: 'Pavel' }),
});
const data = await res.json();

支持流式读取（for await (const chunk of res.body)），适合消费 AI API 的 SSE 输出。总响应上限 32MB。

BotFather 全平台管理

最妙的是：整个项目也可以完全在手机上管理。打开 @BotFather → 你的 Bot → Serverless，你能看到 CLI 管理的一切：

• Handlers —— 创建、编辑、测试 handler
• Library —— 共享的 lib/ 模块
• Database —— 用同样的语法编辑 schema.js
• CLI Access —— 随时拿 token

在手机上写一段 handler，回到电脑上 npx tgcloud pull，这就是你本地的代码了。没有任何东西绑定到特定设备。

一些值得注意的限制

也不是没有坑。目前已知的限制包括：

• 文件上传和下载还不支持。你没法在 handler 里上传新文件或下载文件的字节。官方建议的方式是用 file_id 传引用来绕过。
• 总响应上限 32MB。虽然流式读取可以增量处理大响应，但上限本身不会提高。
• 必须有 Node.js 18+ 才能跑 CLI。这个倒不是什么大问题，毕竟 18 都快 EOL 了。

我的看法

说实话，这是 Telegram 在 Bot 生态上做过的最重要的基础设施更新。

Telegram Bot 的开发者体验一直很分裂——平台本身 API 设计很好，文档清晰，但是部署环节一直是个黑洞。你要么用第三方服务（比如我用的 Hermes Agent），要么自己折腾服务器。这两种方案对只想写一个简单的 /start 回复的人来说，都太重了。

Serverless 补上了这最后一环。它不能直接取代复杂的、需要 GPU 或大规模计算的 Bot 后端。但对于绝大多数 Telegram Bot——消息机器人、小游戏、Mini App 后端、自动化工具——它已经足够了。

而且它和 AI 编码工具配合得很好——每个项目自带 AGENTS.md 和 SDK 参考文档，Claude Code、Cursor 之类的 AI 助手可以直接读。你甚至不需要自己写代码：说一句”写一个记录待办事项的 Bot”，AI 帮你改 schema.js 和 handler，你只需要 review、跑 npx tgcloud run 验证、然后 push + migrate 上线。

这种从开发到部署的无缝体验，才是 2026 年的 Bot 开发该有的样子。