Aiogram в VS Code: настройка окружения для первого бота

Настройка окружения для aiogram-бота в VS Code занимает 20-30 минут, если делать по порядку: поставить нужную версию Python, создать отдельное виртуальное окружение под проект, подключить пару расширений и один раз настроить launch.json для отладки. За несколько лет на фрилансе и в студийных заказах я регулярно вижу одну и ту же картину: человек открывает пустую папку в VS Code, ставит aiogram в системный Python, через пятнадцать минут ловит ModuleNotFoundError или конфликт версий и бросает бота на середине разработки. Ниже - последовательность, которую использую сам на всех проектах, от установки Python до первого запуска бота через отладчик VS Code.

Что понадобится для настройки окружения aiogram в VS Code

Перед тем как открывать VS Code, проверяю четыре вещи, без которых дальше идти бессмысленно.

• Python версии 3.11 или 3.12. aiogram 3.x формально работает от 3.8, но библиотека построена на pydantic 2, и на свежих версиях Python меньше странностей с типизацией и скоростью запуска.
• VS Code с расширением Python от Microsoft - без него редактор не умеет работать с виртуальным окружением и отладчиком.
• Git, даже если бот пока не выкладывается на сервер. Без него неудобно откатывать неудачные правки и работать с .gitignore, о котором ниже.
• Токен бота, полученный у @BotFather в Telegram - без него нет смысла даже начинать.

Установка Python и виртуального окружения в VS Code

Ставлю Python с python.org, при установке обязательно отмечаю пункт «Add python.exe to PATH» - без него терминал VS Code не увидит интерпретатор, и путь придётся прописывать руками. После установки в терминале VS Code проверяю версию командой python --version.

Дальше для каждого бота создаю отдельное виртуальное окружение, а не ставлю библиотеки в системный Python. На практике у меня параллельно живут проекты на aiogram 2 у старых клиентов и aiogram 3 у новых, и без venv они конфликтовали бы через час работы.

# создание окружения
python -m venv venv

# активация на Windows
venv\Scripts\activate

# активация на Mac и Linux
source venv/bin/activate

VS Code обычно сам предлагает выбрать созданное окружение всплывающим уведомлением, но если этого не произошло, открываю палитру команд Ctrl+Shift+P и ввожу Python: Select Interpreter, затем выбираю интерпретатор из папки venv текущего проекта.

Перед первым запуском бота проверяю, что интерпретатор и библиотека совпадают: в терминале при активированном venv выполняю python -c "import aiogram; print(aiogram.__version__)". Версия печатается без ошибок - значит, всё выбрано верно. Если вместо этого вижу ModuleNotFoundError, почти наверняка в статус-баре редактора выбран не тот Python, и стоит вернуться к пункту про Select Interpreter.

Расширения VS Code для разработки бота на aiogram

Ставлю не десяток расширений подряд, а конкретный минимальный набор, который реально использую в каждом проекте.

• Python (ms-python.python) - обязательная база: подсветка синтаксиса, автодополнение, работа с интерпретатором и отладчиком.
• Pylance - анализ типов. Ловит опечатки в названиях полей у Message и CallbackQuery ещё до запуска бота, подсказывает сигнатуры хендлеров aiogram.
• Ruff - линтер и форматтер в одном расширении, у меня заменил связку Black и Flake8, потому что работает заметно быстрее на больших проектах.
• Even Better TOML - пригождается, если конфиг бота вынесен в pyproject.toml.
• GitLens - удобно смотреть, кто и когда правил конкретный хендлер, актуально, если над ботом работают два разработчика.

Настройки форматтера и линтера храню в pyproject.toml, а не раскидываю флаги по разным конфигам - один файл, одни правила, и они одинаково применяются и в терминале, и в самом Ruff внутри VS Code. В settings.json проекта включаю форматирование при сохранении файла, тогда не приходится помнить о запуске форматтера руками перед каждым коммитом.

Структура проекта и установка aiogram 3.x

Структуру проекта держу простой с первого коммита:

• bot.py - точка входа
• handlers/ - роутеры по функциональности (старт, оплата, поддержка)
• filters/ - кастомные фильтры, если стандартных мало
• .env - токен и прочие секреты
• requirements.txt
• .gitignore

Библиотеки ставлю после активации venv: pip install aiogram python-dotenv. Файл зависимостей фиксирую версиями сразу, а не в конце проекта.

aiogram==3.13.1
python-dotenv==1.0.1

Каркас bot.py в aiogram 3.x выглядит так:

import asyncio
import logging
import os

from aiogram import Bot, Dispatcher
from aiogram.client.default import DefaultBotProperties
from aiogram.enums import ParseMode
from dotenv import load_dotenv

from handlers import router

load_dotenv()


async def main() -> None:
    logging.basicConfig(level=logging.INFO)
    bot = Bot(
        token=os.getenv("BOT_TOKEN"),
        default=DefaultBotProperties(parse_mode=ParseMode.HTML),
    )
    dp = Dispatcher()
    dp.include_router(router)
    await dp.start_polling(bot)


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

Когда хендлеров становится больше десяти, разношу их по отдельным файлам внутри handlers и подключаю каждый роутер в bot.py через include_router, а не держу всю логику в одном файле на пятьсот строк - иначе Pylance и сам редактор начинают тормозить на подсказках, да и читать такой файл через месяц тяжело.

Если параллельно веду тестовый и боевой инстансы одного бота, каждому даю отдельную папку и отдельный venv, а не переключаю токены в одном .env - это экономит время при случайном запуске не того бота.

Хранилище состояний FSM: что выбрать на старте

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

Переменные окружения и токен бота

Токен храню только в .env, никогда не пишу его прямо в коде бота.

BOT_TOKEN=123456789:AAExampleTokenFromBotFather

В .gitignore добавляю venv/ и .env с первого коммита, а не когда токен уже засветился в истории репозитория. Если токен всё же попал в публичный репозиторий, самый быстрый способ - зайти к @BotFather и выпустить новый через /revoke, старый после этого перестаёт работать.

Если бот не ограничивается парой команд, а вокруг него нужна интеграция с CRM, приём оплаты или обработка вебхуков от внешнего сервиса, конфигурация быстро выходит за рамки одного токена в .env - в таких случаях обычно беру разработку и интеграцию таких сервисов целиком, от логики бота до вебхуков и хранения данных.

Когда над ботом работает больше одного разработчика, у каждого свой .env с собственным тестовым токеном от отдельного бота, заведённого через BotFather специально для разработки. Боевой токен остаётся только на сервере, а не расходится по личным ноутбукам - это заодно снимает вопрос, кто именно случайно уронил продакшен во время локального теста.

Зависимости для разработки, вроде ruff или pytest, выношу в отдельный requirements-dev.txt, а не смешиваю с боевыми aiogram и python-dotenv - при деплое на сервер ставится только основной файл, и лишние пакеты туда не попадают.

Запуск и отладка бота: launch.json и первые тесты

Через F5 без настройки бот тоже запустится, но без переменных окружения из .env и без точек останова в хендлерах разбираться в падениях дольше. Настраиваю launch.json один раз на проект:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: aiogram bot",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/bot.py",
      "envFile": "${workspaceFolder}/.env",
      "console": "integratedTerminal"
    }
  ]
}

После этого ставлю точку останова прямо в хендлере, нажимаю F5 и на реальном сообщении от бота смотрю содержимое объекта Message или FSMContext, не логируя вручную каждое поле через print.

Локальный запуск: polling или вебхуки

Локально бот почти всегда работает через polling - start_polling сам опрашивает Telegram и не требует внешнего адреса. Это удобно для разработки в VS Code: не нужен ни домен, ни SSL-сертификат, достаточно интернета и токена. На вебхуки перехожу только при переносе бота на сервер, когда важна задержка ответа при большом потоке сообщений - там уже нужен aiohttp, обратный прокси и открытый порт, и это отдельная настройка за рамками локального окружения.

Каждый значимый хендлер проверяю вручную из настоящего Telegram-клиента на телефоне, а не только в тестовом чате внутри VS Code, потому что часть проблем с форматированием HTML в сообщениях или с эмодзи проявляется только на реальном устройстве.

Данные клиентов, номера заказов, историю переписки храню в базе на сервере в России, а не в таблице на стороннем облачном сервисе, даже для тестового прототипа - проще сразу спроектировать хранение правильно, чем переносить готовую базу позже.

Частые ошибки при настройке окружения для aiogram-бота

• VS Code выбрал системный интерпретатор вместо venv. В статус-баре внизу редактора виден путь к другому Python, aiogram установлен, но редактор и терминал его не видят - при импорте выскакивает ModuleNotFoundError.
• Код написан по туториалу под aiogram 2, а установлена aiogram 3.x. Синтаксис Dispatcher, фильтров и хендлеров между версиями различается сильно, и половина примеров из старых статей просто не запустится.
• requirements.txt не зафиксирован версиями. Через пару месяцев pip install ставит другую минорную версию aiogram с изменённым API, и рабочий код перестаёт запускаться без единой правки в самом коде.
• Токен закоммичен в репозиторий вместе с остальным кодом на старте проекта, а .gitignore добавлен через несколько коммитов - токен к этому моменту уже в истории git.
• Для бота с вебхуками через aiohttp не учтена разница в поведении event loop на Windows. В чистом polling-боте на aiogram 3 это почти не встречается, но при связке с aiohttp иногда всплывает.

Частые вопросы

Какая версия Python нужна для aiogram 3?

Формально хватает Python 3.8, но на практике беру 3.11 или 3.12 - меньше конфликтов зависимостей вокруг pydantic 2, на котором построен aiogram 3.x, и быстрее сам интерпретатор.

Почему VS Code не видит aiogram после установки через pip install?

Чаще всего дело в интерпретаторе: терминал активировал одно окружение, а редактор подсвечивает код через другое. Проверяю через Ctrl+Shift+P, Python: Select Interpreter, выбираю venv из папки текущего проекта - после этого автодополнение и запуск начинают работать.

Сколько стоит разработка Telegram-бота на aiogram?

От 30 000 ₽. Итоговая сумма зависит от количества сценариев, интеграций с CRM или оплатой и от того, нужно ли хранилище состояний вроде Redis. Точную оценку даю после короткого обсуждения задачи.

Можно ли обойтись без виртуального окружения?

Технически да, для одного маленького бота это не критично. Но начиная со второго проекта на этом же компьютере версии aiogram и его зависимостей начинают конфликтовать между собой, и разбираться в этом конфликте выходит дольше, чем один раз создать venv.