Bootstrap в Django без боли: пошаговая настройка

К концу этого руководства у вас будет Django-проект с рабочим Bootstrap 5: навигационное меню, сетка и кнопки отрисуются с фирменными стилями, а статика будет отдаваться правильно и в разработке, и при подготовке к продакшену. На всё уйдёт 20–30 минут, если Python и Django уже установлены. Разберём два способа подключения — через CDN и через локальные файлы — и объясним, когда какой выбирать.

Что нужно иметь до начала

Проверьте, что у вас есть, прежде чем что-то делать. На пятом шаге не хочется узнать, что не хватает базовой установки.

• Python 3.10 или новее (python --version).
• Django 5.x, установленный в виртуальном окружении (python -m django --version). Если версия другая — большинство шагов совпадёт, но пути настроек статики стабильны начиная с Django 3.x.
• Уже созданный проект: есть каталог с manage.py и хотя бы одно приложение.
• Версия Bootstrap, о которой идёт речь, — 5.3.x. У пятой ветки нет зависимости от jQuery, это важно для примеров ниже.

Если проекта ещё нет, создайте минимальный: django-admin startproject mysite, затем внутри python manage.py startapp pages. Приложение pages добавьте в INSTALLED_APPS.

Способ 1. Bootstrap через CDN — быстрый старт

Самый короткий путь. Ничего не скачиваете, файлы тянутся с внешнего сервера. Подходит для прототипа, учебного проекта или сайта, где допустима зависимость от внешнего CDN.

1. Создайте каталог для шаблонов и базовый шаблон. В корне проекта: templates/base.html.

   <!doctype html>
   <html lang="ru">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>{% block title %}Мой сайт{% endblock %}</title>
     <!-- Bootstrap 5.3 CSS с CDN -->
     <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
   </head>
   <body>
     {% block content %}{% endblock %}
   
     <!-- JS-бандл с Popper для выпадающих меню и модалок -->
     <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
   </body>
   </html>

2. Укажите Django, где искать templates. В settings.py в списке TEMPLATES в ключе DIRS:

   # settings.py
   import os
   from pathlib import Path
   
   BASE_DIR = Path(__file__).resolve().parent.parent
   
   TEMPLATES = [
       {
           "BACKEND": "django.template.backends.django.DjangoTemplates",
           "DIRS": [BASE_DIR / "templates"],  # вот эта строка
           "APP_DIRS": True,
           # ... остальное без изменений
       },
   ]

3. Создайте страницу, которая наследует базовый шаблон: templates/home.html.

   {% extends "base.html" %}
   
   {% block title %}Главная{% endblock %}
   
   {% block content %}
   <nav class="navbar navbar-expand-lg bg-body-tertiary">
     <div class="container">
       <a class="navbar-brand" href="#">MySite</a>
     </div>
   </nav>
   <div class="container mt-4">
     <h1 class="display-5">Bootstrap подключён</h1>
     <button class="btn btn-primary">Синяя кнопка</button>
   </div>
   {% endblock %}

4. Свяжите view и URL. В urls.py проекта:

   from django.contrib import admin
   from django.urls import path
   from django.views.generic import TemplateView
   
   urlpatterns = [
       path("admin/", admin.site.urls),
       path("", TemplateView.as_view(template_name="home.html")),
   ]

Проверка: запустите python manage.py runserver и откройте http://127.0.0.1:8000/. Кнопка должна быть синей и скруглённой, заголовок — крупным. Если кнопка серая и без стилей — CSS не подтянулся, смотрите раздел про ошибки.

Способ 2. Локальные файлы через collectstatic

CDN хорош для старта, но он даёт внешнюю зависимость: если jsdelivr недоступен, сайт остаётся без стилей. Для продакшена лучше держать Bootstrap у себя. Здесь вступает в игру система статики Django.

Статика в Django живёт в двух режимах. В разработке файлы отдаются прямо из папок приложений. В продакшене их собирают одной командой в единый каталог, который раздаёт веб-сервер. Путаница между этими режимами — источник большинства «почему стили не грузятся».

1. Скачайте скомпилированный Bootstrap с официального сайта getbootstrap.com (раздел Download, ветка 5.3.x). Внутри архива нужны bootstrap.min.css и bootstrap.bundle.min.js.

2. Положите их в каталог статики. Создайте в корне проекта структуру и разложите файлы:

   static/
     css/
       bootstrap.min.css
     js/
       bootstrap.bundle.min.js

3. Настройте пути статики в settings.py. Здесь важны три параметра:

   # settings.py
   STATIC_URL = "/static/"
   
   # откуда collectstatic берёт файлы в разработке
   STATICFILES_DIRS = [BASE_DIR / "static"]
   
   # куда collectstatic складывает всё для продакшена
   STATIC_ROOT = BASE_DIR / "staticfiles"

   Разница между этими двумя каталогами — ключевая, вынесем её в таблицу ниже.

4. Подключите файлы в base.html через тег {% static %} вместо ссылок на CDN:

   {% load static %}
   <!doctype html>
   <html lang="ru">
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>{% block title %}Мой сайт{% endblock %}</title>
     <link href="{% static 'css/bootstrap.min.css' %}" rel="stylesheet">
   </head>
   <body>
     {% block content %}{% endblock %}
     <script src="{% static 'js/bootstrap.bundle.min.js' %}"></script>
   </body>
   </html>

   Тег {% load static %} должен стоять в начале файла, до первого использования {% static %}.

5. Проверьте, что в INSTALLED_APPS есть django.contrib.staticfiles — по умолчанию он там. Именно он даёт тег {% static %} и команду collectstatic.

Проверка в разработке: с DEBUG = True запустите runserver — файлы отдаются автоматически из STATICFILES_DIRS, никаких дополнительных команд не нужно. Откройте страницу: стили на месте.

Проверка перед продакшеном: выполните python manage.py collectstatic. В консоли появится строка вида «X static files copied to '.../staticfiles'». После этого каталог staticfiles раздаёт Nginx или другой сервер — сам Django с DEBUG = False статику не отдаёт.

STATICFILES_DIRS против STATIC_ROOT

Эти два параметра путают чаще всего. Указать один вместо другого — и collectstatic либо ничего не найдёт, либо перезапишет ваши исходники.

STATIC_ROOT и папки из STATICFILES_DIRS не должны совпадать — Django на это ругается при запуске collectstatic.

CDN или локальные файлы: что выбрать

• CDN — прототип, демо, обучение. Ноль настройки, но зависимость от внешнего сервиса и невозможность работать офлайн.
• Локальные файлы — любой проект, который дойдёт до продакшена. Контроль версии, работа без интернета, никакой сторонней аналитики в запросах.

Пакеты вроде django-bootstrap5[1] дают шаблонные теги для форм и заметно упрощают вёрстку Django-форм. Это отдельная тема — здесь мы подключаем чистый Bootstrap руками, чтобы понимать, что происходит под капотом.

Если не получилось

Пять ошибок, которые встречаются почти всегда.

• Страница без стилей, кнопки серые. Откройте вкладку Network в браузере: если запрос к bootstrap.min.css отдаёт 404 — путь в {% static %} не совпадает с реальным расположением файла внутри static/.
• Invalid block tag 'static' в шаблоне. Забыли {% load static %} в начале файла. Тег статики не работает без загрузки библиотеки тегов.
• TemplateDoesNotExist: home.html. Django не видит папку templates. Проверьте, что она указана в TEMPLATES → DIRS, и что путь собран через BASE_DIR, а не хардкодом.
• После collectstatic с DEBUG = False стили пропали. С отключённым дебагом Django не раздаёт статику сам. Это задача веб-сервера. В разработке верните DEBUG = True или используйте пакет для локальной отдачи собранной статики.
• Выпадающее меню и модалки не открываются. Подключили только CSS, забыли JS-бандл. Bootstrap 5 нужен bootstrap.bundle.min.js (в нём уже есть Popper) перед закрывающим </body>.

Что делать дальше

Базовый шаблон готов, дальше наращивайте. Разбейте base.html на блоки для футера и боковой панели. Если в проекте много форм — посмотрите в сторону django-bootstrap5, он избавит от ручной разметки классов у каждого поля. Перед выкаткой на боевой сервер настройте раздачу каталога STATIC_ROOT через Nginx и один раз прогоните collectstatic в пайплайне деплоя — тогда стили не отвалятся в продакшене.

[1] Тег шаблона (template tag) — конструкция в фигурных скобках с процентами, например {% static %}, которую Django обрабатывает при рендеринге страницы и заменяет на результат: путь, кусок HTML или значение переменной.