botfromzero
本章目录
    Telegram 机器人实战 › 第 2 部分 · 把它跑起来

    第 2 章

    把它跑起来

    这一章唯一的目标：让它回你第一句话。大部分人卡住的地方不在代码，在环境——所以每一步都配了「报错了怎么办」。

    约 30 分钟装环境占一大半时间aiogram 3.x · 最后验证 2026-08
    01

    先去 BotFather 领一个机器人

    这一步全程在 Telegram 里完成，不写代码，五分钟。

    打开 Telegram，搜索 @BotFather（注意认准带蓝勾的那个），点进去发 /newbot。它会问你两个名字：

    显示名用户看到的名字，中文、空格、emoji 都行。比如「签到助手」。随时能改。
    username唯一标识，必须以 bot 结尾，全局唯一，而且建了就改不了。比如 my_checkin_bot。
    好名字基本都被占了。别在这儿纠结，加个后缀就行 —— 这个名字对你的学习过程毫无影响。

    建好之后 BotFather 会回你一段话，里面有一行就是 token，长这样：

    BotFather 的回复
    Use this token to access the HTTP API:7284916350:AAHk9Lm2pQxV-fN3rTz8bWcY1sD4eG6hJ0

    先复制到记事本里，等下要用。别发给任何人，别截图发群里。

    ✓ 顺手确认一件事

    在 BotFather 里发 /mybots → 选你刚建的 → Bot Settings → Group Privacy，确认它是 Enabled（默认就是）。第 1 章说过，这决定了它在群里能收到哪些消息。现在保持默认，做群功能时再回来改。

    02

    准备 Python 环境

    这一节是整套教程流失最多的地方，跟会不会写代码没关系。慢一点，每步都确认成功了再往下。

    先看你的 Python 版本

    打开终端（Windows 用 PowerShell），敲：

    终端
    python3 --version

    要看到 3.10 或更高。如果提示「命令未找到」，换成 python --version 再试一次 —— Windows 上通常是这个。

    你看到的怎么办
    Python 3.10 及以上直接往下走
    Python 3.9 及以下去 python.org 装个新的。aiogram 3 要 3.10+，装老版本后面会报奇怪的语法错误
    两个命令都说找不到没装 Python。macOS 用 brew install python，Windows 去 python.org 下载器装（勾上 Add to PATH），Ubuntu 用 apt install python3 python3-venv

    建目录，建虚拟环境

    虚拟环境的作用是：这个项目装的包只待在这个文件夹里，不会污染你系统里的 Python。不用理解原理，照做就行，三行命令。

    macOS / LinuxWindows (PowerShell)
    建目录mkdir my-bot && cd my-bot
    建环境python3 -m venv .venvpython -m venv .venv
    激活source .venv/bin/activate.venv\Scripts\Activate.ps1
    激活成功的标志：命令行提示符前面多了一个 (.venv)。没看到就是没激活，后面装的包会跑到别处去。
    ◆ Windows 上激活报「禁止运行脚本」

    PowerShell 默认不让跑脚本。在管理员 PowerShell 里执行一次 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，然后重开终端再激活。这是一次性设置。

    装 aiogram

    确认命令行前面有 (.venv)，然后：

    终端
    pip install aiogram python-dotenv

    国内网络装得慢或者直接失败的话，换个源：

    终端 · 换成清华源
    pip install aiogram python-dotenv -i https://pypi.tuna.tsinghua.edu.cn/simple

    装完验证一下，这行不报错就说明成了：

    终端
    python -c "import aiogram; print(aiogram.__version__)"
    03

    代理：国内网络必看

    第 1 章那张图里，第 2 步和第 4 步都是你的程序去连 Telegram 的服务器。这条路在国内是不通的 —— 哪怕你的浏览器能打开 Telegram，你的 Python 程序也不一定能。

    先测一下你到底需不需要

    终端 · 把 <TOKEN> 换成你的
    curl https://api.telegram.org/bot<TOKEN>/getMe

    返回一段带 "ok":true 的 JSON，说明网络通，这一节可以跳过。如果卡住不动或者报连接错误，往下看。

    把代理告诉程序

    你本机的代理软件（Clash、V2Ray 之类）会监听一个本地端口，常见的是 7890 或 1080。在软件设置里能看到具体是哪个。

    拿到端口后，先用 curl 验证这条路走得通：

    终端
    curl -x http://127.0.0.1:7890 https://api.telegram.org/bot<TOKEN>/getMe

    这次通了的话，记住这个地址，下一节写进配置里。

    ◆ 别把代理软件的「系统代理」开关当成万能的

    很多代理软件的「系统代理」模式对 Python 程序不生效 —— 浏览器能上，程序不能上，就是这个原因。所以要在代码里显式指定，下一节就做。

    04

    写代码

    一共两个文件。先建 .env，token 放这儿，不放代码里：

    .env
    BOT_TOKEN=7284916350:AAHk9Lm2pQxV-fN3rTz8bWcY1sD4eG6hJ0# 不需要代理就把下面这行删掉或注释掉PROXY_URL=http://127.0.0.1:7890

    再建一个 .gitignore，防止哪天手滑把 token 传上 GitHub：

    .gitignore
    .env.venv/__pycache__/

    然后是主程序 bot.py：

    bot.pyaiogram 3.x
    import asyncioimport loggingimport osfrom aiogram import Bot, Dispatcher, Routerfrom aiogram.client.session.aiohttp import AiohttpSessionfrom aiogram.filters import Commandfrom aiogram.types import Messagefrom dotenv import load_dotenvload_dotenv()logging.basicConfig(level=logging.INFO)router = Router()@router.message(Command("start"))async def cmd_start(message: Message) -> None:    await message.answer("你好，我活着")async def main() -> None:    token = os.getenv("BOT_TOKEN")    if not token:        raise SystemExit("没读到 BOT_TOKEN，检查 .env 文件")    # 有 PROXY_URL 就走代理，没有就直连    proxy = os.getenv("PROXY_URL")    session = AiohttpSession(proxy=proxy) if proxy else None    bot = Bot(token=token, session=session)    dp = Dispatcher()    dp.include_router(router)    me = await bot.get_me()    logging.info("启动成功：@%s", me.username)    await dp.start_polling(bot)if __name__ == "__main__":    asyncio.run(main())

    比第 1 章那个最小版本多了三样东西，都是为了让你少踩坑：

    load_dotenv() + os.getenvtoken 从 .env 读，不写死在代码里
    AiohttpSession(proxy=...)显式指定代理。这是国内能不能跑起来的关键一行
    await bot.get_me()启动时先问一句「我是谁」。这行能让你立刻知道 token 和网络对不对，不用等到发消息才发现
    05

    跑

    终端
    python bot.py

    看到这一行，说明连上了：

    输出
    INFO:root:启动成功：@my_checkin_botINFO:aiogram.dispatcher:Start polling

    别关终端。现在去 Telegram 搜你的 bot 用户名，点 Start，或者发一句 /start。

    ✓ 它回你了

    这就是第一次成功。你现在有一个真正在运行的 Telegram 机器人 —— 它跑在你这台电脑上，通过你的终端那个进程活着。按 Ctrl+C，它就死了；再 python bot.py，它又活了。这就是第 1 章讲的那件事。

    06

    没跑起来？对着这张表找

    下面是真实高频的报错，按出现频率排。先看报错的最后一行，那才是关键信息。

    报错里的关键词原因和解法
    ModuleNotFoundError: No module named 'aiogram' 虚拟环境没激活。看看命令行前面有没有 (.venv)，没有就重新 activate 一次，再 pip install。这条占了所有报错的三成。
    没读到 BOT_TOKEN .env 不在你运行 python bot.py 的那个目录里；或者文件名被存成了 .env.txt（Windows 记事本的经典坑）。用 ls -a / dir 确认一下。
    TelegramUnauthorizedError
    Unauthorized    		 token 错了。常见于复制时少了一位、多了空格、或者把 BotFather 那句提示文字也粘进去了。回 BotFather 发 /mybots 重新拿一次。
    TelegramNetworkError
    ClientConnectorError
    Connection timeout    		 网络到不了 Telegram。回到第 3 节，先用 curl 验证代理通不通，再确认 .env 里的 PROXY_URL 端口跟你代理软件里的一致。
    TelegramConflictError
    terminated by other getUpdates    		 同一个 bot 你开了两个进程。另一个终端窗口里可能还跑着。全部 Ctrl+C 关掉，只留一个。
    SyntaxError 指向 async def 那行 Python 版本太老。回第 2 节确认是 3.10+。
    SSLError / SSLCertVerificationError（装包时） pip 走不通。换清华源那条命令再试。公司网络还可能要加 --trusted-host pypi.tuna.tsinghua.edu.cn。
    程序跑着，但发消息没反应 确认你发的是 /start（带斜杠），而且找的是自己刚建的那个 bot —— 重名的很多，认准 username。
    表里没有你的报错？把最后三行原样贴到本页底部的「我卡在这里了」，这类反馈会直接变成这张表的新行。

    你现在有什么了

    1. 一个属于你的 bot，和一串 token（放在 .env 里，没有写进代码）
    2. 一个隔离的 Python 环境，装好了 aiogram
    3. 一份能跑通的 bot.py，里面已经带上了代理开关和启动自检
    4. 知道它活在你的终端进程里 —— 关掉就没了
    ✓ 先别关，试个东西

    把 cmd_start 里的回复文字改一句，保存，然后回终端 Ctrl+C 再重新 python bot.py，去 Telegram 再发一次 /start。
    改代码必须重启才生效 —— 这个来回你后面会做几百遍，现在先熟悉一下手感。

    卡在哪一步了？

    装环境最容易出问题。报错原文直接贴进来，越具体我越能帮上忙。留不留联系方式都行。