Aiogram в PyCharm: первый бот на API 3.x

PyCharm отвечает за проект и запуск интерпретатора, а aiogram — за обработку Telegram Bot API. Сначала согласуйте виртуальное окружение IDE и терминала. Код ниже рассчитан на aiogram 3.x: примеры с Dispatcher(bot), message_handler и executor относятся к старому API и не должны смешиваться с ним.

Подготовить проект

Создайте проект Python с отдельным виртуальным окружением и выберите его в настройках интерпретатора. В терминале этого же окружения:

python -c "import sys; print(sys.executable)"
python -m pip install "aiogram>=3,<4"
python -m pip show aiogram

Получите токен своего бота через официальный BotFather. В конфигурации запуска PyCharm задайте переменную окружения BOT_TOKEN. Не вставляйте токен в исходник, скриншот, историю команд или репозиторий. Если он раскрыт, отзовите его у BotFather и замените настройку.

Один обработчик и один процесс polling

import asyncio
import os

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message

dispatcher = Dispatcher()

@dispatcher.message(CommandStart())
async def start(message: Message):
    await message.answer("Готов ответить. Это тестовый бот.")

async def main():
    token = os.environ["BOT_TOKEN"]
    bot = Bot(token=token)
    await dispatcher.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())

Сохраните файл как bot.py, запустите его выбранным интерпретатором и отправьте /start своему боту. Обработчик должен вернуть указанную фиксированную фразу. Он отвечает на команду, а не рассылает сообщения неизвестным пользователям. Для остановки завершите процесс обычным Ctrl+C.

Почему не приходят ответы

• ModuleNotFoundError обычно требует сверить интерпретатор, а не повторять pip install в другом терминале.
• KeyError BOT_TOKEN означает, что переменная не передана именно этому запуску. Не печатайте значение токена для проверки.
• У одного токена должен работать только один polling-процесс. Проверьте второй запуск в IDE, терминале и на сервере.
• Polling и настроенный webhook требуют согласованного режима. Не удаляйте существующий webhook рабочего бота только ради локального эксперимента: используйте отдельного тестового бота.

Следующий шаг

Добавляйте Router и явные фильтры по типу сообщения. Сообщение с фото не обязано иметь text, поэтому универсальный обработчик с message.text.lower() может упасть. При журналировании сохраняйте тип ошибки и технический контекст без токена и содержимого переписки. Сначала проверьте новую ветку на тестовом боте.