Использование `mkcert` для включения https на локальных сайтах

Ищете способ быстро настроить безопасное соединение для тестирования веб-приложений? Хотите пропустить статью и сразу приступить к делу? Перейдите в репозиторий FiloSottile/mkcert и следуйте инструкции в README.

Проблема с HTTPS в локальной разработке

Современная веб-разработка значительно эволюционировала от простых HTML-страниц. Сегодня сложные приложения — одностраничные (SPA), прогрессивные веб-приложения (PWA), системы с авторизацией — нуждаются в защищённом соединении уже на стадии создания. Протокол HTTP, не использующий шифрование, больше не соответствует требованиям таких проектов.

Почему локальный HTTPS стал необходимостью

Основные проблемы, с которыми сталкиваются разработчики при использовании HTTP на локальных доменах (localhost, project.test, app.local):

• Предупреждения безопасности браузеров. Chrome, Firefox, Safari и Edge последовательно помечают HTTP-сайты как «Небезопасные». Это не просто значок — часто это полноэкранные блокировки, прерывающие рабочий процесс.
• Блокировка функциональности. Многие современные API браузера, такие как геолокация, доступ к камере/микрофону, отправка уведомлений и работа сервис-воркеров, требуют безопасного контекста (HTTPS или localhost). На кастомных локальных доменах (не localhost) эти функции на HTTP недоступны.
• Сложности с отладкой. Предупреждения мешают корректной эмуляции пользовательского сценария. Проблемы, связанные с политиками безопасности (CORS, Cookies с флагом Secure), невозможно полноценно воспроизвести.
• Невозможность тестирования в реалистичных условиях. Процессы OAuth-авторизации, платёжные шлюзы и веб-хуки часто требуют HTTPS-энтрпоинтов для callback, что делает их локальное тестирование на HTTP затруднительным.

Ограничения традиционных методов

Классический подход — создание самоподписанного SSL-сертификата с помощью OpenSSL — был стандартом долгое время. Однако сегодня этот метод сопряжён с существенными накладными расходами:

1. Ручная настройка доверия. Полученный сертификат необходимо вручную импортировать и добавить в список доверенных в хранилище каждой операционной системы и каждого браузера отдельно. Это трудоёмкий и неочевидный процесс, особенно для начинающих разработчиков.
2. Стойкие предупреждения. Даже после импорта браузеры часто продолжают отображать предупреждения о ненадёжном сертификате, поскольку он не проходит стандартную цепочку проверки.
3. Сложности с кросс-платформенностью и мобильными устройствами. Настройка доверия на macOS, Windows и Linux отличается. Для тестирования на смартфонах или планшетах в локальной сети процесс становится ещё более запутанным.
4. Проблемы с поддоменами. Для каждого поддомена или при использовании wildcard-доменов требуется отдельная сложная процедура или генерация нового сертификата.
5. Временные решения. Сертификаты имеют ограниченный срок действия, требуют периодического обновления и повторной настройки, отвлекая от основной задачи — разработки.

Таким образом, потребность в простом, надёжном и кросс-платформенном решении для локального HTTPS стала критически важной для эффективного рабочего процесса. Инструмент mkcert был создан именно для решения этого комплекса проблем.

Что такое mkcert и чем он лучше

Для решения описанных выше проблем существует утилита командной строки с открытым исходным кодом — mkcert. В отличие от традиционных подходов, mkcert решает проблему локального HTTPS принципиально иным способом. Вместо создания отдельных самоподписанных сертификатов для каждого домена, mkcert устанавливает на ваш компьютер локальный центр сертификации (Local Certificate Authority, Local CA).

Принцип работы:

1. Установка доверенного корня. При первом запуске команды mkcert -install программа создаёт пару ключей (публичный и приватный) для вашего личного CA и добавляет его публичный сертификат в системные хранилища доверенных корневых сертификатов вашей операционной системы. Это делается автоматически.
2. Доверие браузеров. Поскольку браузеры (Chrome, Firefox, Edge, Safari) используют системное хранилище сертификатов, они начинают автоматически доверять любому сертификату, выпущенному этим локальным CA.
3. Генерация валидных сертификатов. Когда вы создаёте сертификат для localhost или myproject.test командой mkcert myproject.test, mkcert подписывает его приватным ключом вашего локального CA. Браузер, видя подпись от доверенного (в рамках вашей системы) центра, считает такой сертификат полностью легитимным и безопасным.

Ключевые преимущества перед ручными методами и OpenSSL

Ключевое отличие mkcert от ручной генерации сертификатов заключается в автоматизации и корректной интеграции в систему безопасности операционной системы. Вместо того чтобы каждый раз уговаривать браузер принять очередной самоподписанный сертификат, mkcert однократно настраивает доверенный источник этих сертификатов. Сравнение основных характеристик наглядно демонстрирует разницу в подходах:

Поддерживаемые платформы и сценарии

mkcert официально поддерживает:

• Операционные системы: Windows (через WSL или нативно), macOS, Linux.
• Браузеры: Все основные, включая Chrome, Firefox, Safari, Edge.
• Веб-серверы: Любые, работающие с SSL/TLS (Nginx, Apache, Caddy, встроенные серверы Node.js, PHP, Python и др.).
• Типы имён: Локальные домены (app.test), localhost, IP-адреса (127.0.0.1, 192.168.1.5), wildcard-поддомены (*.app.test).

Итог: mkcert не обходит систему безопасности, а корректно интегрируется в неё. Он создаёт для разработчика персональную, изолированную среду с полностью валидным HTTPS, эмулируя работу с реальным SSL-сертификатом, но без сложностей, связанных с его получением и настройкой. Это переводит HTTPS из разряда проблемы инфраструктуры в категорию простого инструмента разработки.

Установка mkcert

Установка mkcert выполняется в несколько простых шагов и зависит от вашей операционной системы. Независимо от выбранного метода, результатом будет появление исполняемого файла mkcert в системе, доступного из командной строки (терминала).

Перед началом установки:

• Убедитесь, что у вас есть доступ к командной строке (Terminal, PowerShell, Command Prompt, Bash).
• Для некоторых методов установки потребуются права администратора/суперпользователя (sudo на Linux/macOS, запуск от имени администратора на Windows).

Установка на macOS

На macOS установку проще всего выполнить с помощью менеджера пакетов Homebrew. Если он у вас не установлен, следуйте инструкциям на brew.sh.

brew install mkcert
brew install nss # если используете Firefox

Альтернативный вариант через MacPorts:

sudo port install mkcert
sudo port install nss # если используете Firefox

После установки система автоматически обновила пути. Вы можете проверить успешность установки, выполнив в терминале: mkcert --version.

Установка на Windows

На Windows можно использовать один из популярных менеджеров пакетов или загрузить готовую исполняемую версию.

Вариант 1: Chocolatey (рекомендуется):

1. Если у вас ещё не установлен Chocolatey, выполните инструкцию с официального сайта.
2. Установите mkcert из запущенных с права администратора PowerShell или Командной строки:

   choco install mkcert

Вариант 2: Scoop:

1. Установите Scoop, если его нет.
2. Добавьте bucket extras и установите mkcert:

   scoop bucket add extras
   scoop install mkcert

Вариант 3: Готовый бинарный файл (самый простой):

1. Загрузите последнюю версию mkcert-vX.X.X-windows-amd64.exe со страницы релизов на GitHub.
2. Переименуйте файл в mkcert.exe.
3. Поместите его в директорию, которая есть в системной переменной PATH (например, C:\Windows\System32\), или добавьте путь к файлу в PATH вручную. Это позволит вызывать mkcert из любой директории.

Установка на Linux

Процедура установки на Linux зависит от вашего дистрибутива и выбранного менеджера пакетов.

Предварительный шаг для всех дистрибутивов: Установите утилиту certutil, необходимую для интеграции с Firefox.

sudo apt install libnss3-tools

sudo yum install nss-tools

sudo pacman -S nss

sudo zypper install mozilla-nss-tools

Основная установка mkcert:

brew install mkcert

sudo pacman -Syu mkcert

git clone https://github.com/FiloSottile/mkcert && cd mkcert
go build -ldflags "-X main.Version=$(git describe --tags)"

Настройка и использование

После успешной установки mkcert необходимо выполнить два ключевых действия: установить локальный центр сертификации (CA) в систему и сгенерировать SSL/TLS-сертификаты для ваших проектов. Этот раздел проведёт вас через весь процесс.

Первоначальная настройка (установка локального CA)

Перед генерированием сертификатов для отдельных сайтов необходимо однократно установить локальный центр сертификации. Эта операция добавляет корневой сертификат mkcert в хранилища доверия вашей операционной системы и браузеров.

1. Откройте терминал (командную строку).
2. Выполните команду:

   mkcert -install

3. При успешном выполнении вы увидите сообщение, подобное этому:

   Created a new local CA at "/Users/username/Library/Application Support/mkcert"
   The local CA is now installed in the system trust store!
   The local CA is now installed in the Firefox trust store (requires browser restart)!

Что произошло:

• В специальной директории пользователя были созданы файлы корневого сертификата (rootCA.pem) и приватного ключа (rootCA-key.pem).
• Корневой сертификат был автоматически добавлен в системное хранилище доверенных центров сертификации.
• Для Firefox (использующего собственное хранилище NSS) сертификат также был установлен.

Генерация SSL-сертификатов

После установки CA вы можете создавать валидные SSL-сертификаты для любых локальных имён. Рекомендуется генерировать сертификаты в директории вашего проекта, например, в папке ssl/ или certs/.

Базовое использование:

# Перейдите в директорию вашего проекта
cd ~/projects/my-website

# Создайте сертификат для одного домена
mkcert mywebsite.local

# Будет создано два файла:
# - mywebsite.local.pem      (сертификат)
# - mywebsite.local-key.pem  (приватный ключ)

Расширенные возможности:

mkcert позволяет указать несколько имён (SAN — Subject Alternative Names) для одного сертификата, что очень удобно для сложных сред разработки.

# Сертификат для локального домена, всех его поддоменов и localhost
mkcert "*.mywebsite.local" mywebsite.local localhost

# Сертификат для домена, IP-адреса и loopback-адреса
mkcert mysite.test 192.168.1.10 127.0.0.1 ::1

Настройка веб-серверов (общие шаги)

После генерации файлов сертификата (.pem) и ключа (-key.pem) их необходимо указать в конфигурации вашего веб-сервера. Общий алгоритм для любого сервера (Nginx, Apache, Caddy и др.) выглядит так:

1. Найдите конфигурационный файл вашего виртуального хоста или основную конфигурацию сервера.
2. Активируйте SSL/TLS для нужного порта (обычно 443).
3. Укажите пути к созданным файлам в соответствующих директивах:
   • ssl_certificate / SSLCertificateFile — путь к файлу сертификата (.pem).
   • ssl_certificate_key / SSLCertificateKeyFile — путь к файлу приватного ключа (-key.pem).
4. Перезапустите веб-сервер, чтобы применить изменения.

Проверка работы: Откройте браузер и перейдите по HTTPS-адресу вашего сайта (например, https://mywebsite.local). В адресной строке должен отображаться значок замка, а при его нажатии — статус Безопасное соединение. Сертификат должен быть выдан вашим локальным CA (например, mkcert development CA).

Следующий раздел содержит готовые примеры конфигураций для самых популярных веб-серверов: Nginx и Apache.

Примеры конфигураций

Конфигурация для Nginx

Для современных версий Nginx используйте отдельную директиву http2:

...
server {
    listen 443 ssl;
    http2 on;  # Актуальный способ включения HTTP/2
    server_name myproject.local;

    # Пути к сертификатам, созданным mkcert
    ssl_certificate /var/www/myproject/certs/myproject.local.pem;
    ssl_certificate_key /var/www/myproject/certs/myproject.local-key.pem;

    # Рекомендуемые настройки SSL
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
...
}

Если используется более старая версия Nginx, можно оставить старый формат:

listen 443 ssl http2;  # Для версий до ~1.25.0

Конфигурация для Apache

Проверяем конфигурацию Apache. В современных версиях Apache (2.4+) SSL/TLS настройки в целом остались прежними, но обновим некоторые параметры:

...
<VirtualHost *:443>
    ServerName myproject.test
    ServerAdmin webmaster@myproject.test
    DocumentRoot /var/www/myproject/public

    # Активация SSL
    SSLEngine on

    # Пути к сертификатам, созданным mkcert
    SSLCertificateFile /var/www/myproject/certs/myproject.test.pem
    SSLCertificateKeyFile /var/www/myproject/certs/myproject.test-key.pem

    # Современные настройки SSL/TLS
    SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1 +TLSv1.2 +TLSv1.3
    SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384
    SSLHonorCipherOrder off
    SSLCompression off
...
</VirtualHost>

Конфигурация для Caddy

Поскольку Caddy становится популярным выбором для разработки, добавлю пример и для него:

myproject.local {
    root * /var/www/myproject/public
    file_server

    # Caddy автоматически получает сертификаты Let's Encrypt,
    # но для локальной разработки с mkcert:
    tls /var/www/myproject/certs/myproject.local.pem /var/www/myproject/certs/myproject.local-key.pem

    # PHP-FPM
    php_fastcgi unix//var/run/php/php8.2-fpm.sock

    # Заголовки безопасности
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy strict-origin-when-cross-origin
    }
}

Решение частых проблем

Даже при использовании такого удобного инструмента, как mkcert, могут возникнуть определённые сложности. В этом разделе рассмотрим наиболее распространённые проблемы и способы их решения.

Проблемы с браузерами

Симптом 1: Браузер продолжает показывать предупреждение о небезопасном соединении

Причина: Локальный центр сертификации (CA) не установлен или не доверен в браузере.

Решение:

1. Убедитесь, что команда mkcert -install была выполнена успешно.
2. Перезапустите браузер. Иногда требуется полный перезапуск, а не просто перезагрузка вкладки.
3. Для Firefox: Проверьте, установлен ли пакет nss (или libnss3-tools на Linux) и был ли браузер перезапущен после установки CA. Firefox использует собственное хранилище сертификатов (NSS). Можно вручную проверить наличие сертификата в настройках Firefox: Настройки → Приватность и защита → Просмотр сертификатов → вкладка Центры сертификации. Ищите запись mkcert development CA.
4. Для Chrome/Edge: Они используют системное хранилище. Убедитесь, что корневой сертификат mkcert присутствует там.

Симптом 2: В разных браузерах разное поведение (в одном работает, в другом нет)

Причина: Несогласованность хранилищ сертификатов между браузерами и системой.

Решение:

1. Выполните mkcert -install повторно.
2. Удалите корневой сертификат mkcert из всех хранилищ (системного и браузерных) и установите заново. Для удаления в macOS используйте Keychain Access, в Windows — certmgr.msc, в Linux — инструменты управления сертификатами вашего дистрибутива.

Симптом 3: Ошибка NET::ERR_CERT_AUTHORITY_INVALID или аналогичная

Причина: Сертификат для конкретного домена не был подписан установленным CA, или CA не доверен.

Решение: Удалите существующие сертификаты для домена (файлы .pem) и сгенерируйте их заново командой mkcert вашдомен.local.

Ошибки установки и права доступа

Симптом 1: Команда mkcert не найдена

Причина: Исполняемый файл не находится в системной переменной PATH.

Решение:

• Перезагрузите терминал после установки.
• Убедитесь, что директория, в которую установлен mkcert, добавлена в PATH (актуально для Windows при установке бинарным файлом и для Linux при сборке из исходников).
• Попробуйте использовать полный путь к исполняемому файлу.

Симптом 2: Ошибка доступа при выполнении mkcert -install

Причина: Недостаточно прав для записи в системное хранилище сертификатов.

Решение:

• macOS/Linux: Запустите команду с sudo: sudo mkcert -install. Обратите внимание, что в этом случае корневой сертификат будет установлен для всех пользователей системы.
• Windows: Запустите терминал (PowerShell или CMD) от имени администратора.

Симптом 3: Ошибки при установке через менеджер пакетов

Решение:

• Обновите менеджер пакетов (brew update, choco upgrade, sudo apt update).
• Проверьте подключение к интернету.
• Рассмотрите альтернативный способ установки (например, через готовый бинарный файл).

Сертификат не работает для поддоменов

Симптом: HTTPS работает для основного домена (например, site.local), но не для поддомена (api.site.local)

Причина: Сертификат не содержит необходимого имени (Subject Alternative Name).

Решение: Перегенерируйте сертификат, явно указав все необходимые домены и поддомены.

# Неправильно (не будет работать для api.site.local):
mkcert site.local
# Правильно (работает для всех поддоменов и основного домена):
mkcert "*.site.local" site.local

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

Часто задаваемые вопросы (FAQ)

В этом разделе собраны ответы на наиболее распространённые вопросы, которые возникают у разработчиков при использовании mkcert.

Вопрос 1: Насколько безопасно использование mkcert на рабочей машине?

Ответ: mkcert создаёт безопасную изолированную среду только для локальной разработки. Принцип его работы основан на корректной интеграции с системой безопасности вашего компьютера, а не на её обходе.

• Что безопасно: Локальный центр сертификации (CA) и генерируемые им сертификаты безопасности работают только на вашем компьютере. Они не могут быть использованы для атак на другие системы или для выдачи цифровых сертификатов для публичных доменов (например, google.com).
• Главный риск: Приватный ключ корневого CA (rootCA-key.pem). Если злоумышленник получит к нему доступ, он сможет создавать сертификаты, которым будет доверять ваш компьютер. Поэтому этот файл необходимо хранить в безопасности и никогда не передавать.
• Рекомендация: Используйте mkcert исключительно в целях разработки. Для публичных (продакшен) сайтов всегда используйте сертификаты от общедоступных центров сертификации, таких как Let's Encrypt.

Вопрос 2: Нужно ли обновлять или продлевать сертификаты, созданные mkcert?

Ответ: Сертификаты, созданные mkcert, имеют очень длительный срок действия (обычно до 825 дней, что составляет более 2 лет). На практике это означает, что для целей локальной разработки вам, скорее всего, не придётся заниматься их продлением. Они будут работать годами.

Однако, если срок действия сертификата безопасности истёк или вы хотите обновить список доменов (SAN), просто удалите старые файлы (.pem) и сгенерируйте сертификат заново с помощью команды mkcert.

Вопрос 3: Как полностью удалить mkcert и его цифровые сертификаты с компьютера?

Ответ: Для полного удаления необходимо убрать как сам инструмент, так и установленный им центр сертификации.

1. Удалите исполняемый файл mkcert: Способ зависит от метода установки.
   • Homebrew (macOS/Linux): brew uninstall mkcert
   • Chocolatey (Windows): choco uninstall mkcert
   • Вручную: Удалите файл mkcert (или mkcert.exe) из директории, куда он был установлен.
2. Удалите локальный центр сертификации (CA) из системы:
   • Выполните команду mkcert -uninstall перед удалением самого бинарного файла. Если mkcert уже удалён, придётся удалить CA вручную.
   • macOS: Откройте Keychain Access (Связку ключей). Найдите в категории Сертификаты запись mkcert development CA и удалите её.
   • Windows: Откройте certmgr.msc (Диспетчер сертификатов). В Доверенные корневые центры сертификации → Сертификаты найдите и удалите mkcert development CA.
   • Linux: Удалите файлы из директории, которую показывает команда mkcert -CAROOT (обычно ~/.local/share/mkcert или /root/.local/share/mkcert).

Вопрос 4: Можно ли использовать сертификаты mkcert для тестирования на мобильных устройствах в локальной сети?

**Ответ: Да, это возможно, но требует дополнительных шагов. **Так как ваш телефон или планшет не доверяют вашему локальному CA по умолчанию, необходимо вручную установить корневой сертификат mkcert на мобильное устройство.

1. Найдите корневой сертификат на компьютере: Выполните команду mkcert -CAROOT. В указанной директории будет файл rootCA.pem.
2. Передайте файл rootCA.pem на мобильное устройство (например, по электронной почте, через облако или локальный HTTP-сервер).
3. Установите сертификат на устройстве:
   • iOS: Откройте файл в приложении Почта или Файлы, система предложит установить профиль. После установки перейдите в Настройки → Основные → Об этом устройстве → Сертификаты доверия и включите доверие для mkcert development CA.
   • Android: Откройте файл в менеджере файлов, система запросит имя для сертификата. Установите его как Сертификат CA. Процесс может незначительно отличаться в зависимости от версии Android и оболочки производителя.

Вопрос 5: Почему mkcert не создаёт сертификаты для публичных доменов (например, .com, .ru)?

Ответ: mkcert специально ограничен работой с локальными именами (localhost, домены .test, .local, .localhost, локальные IP-адреса). Это преднамеренное ограничение в целях безопасности, чтобы предотвратить случайную или злонамеренную выдачу валидных сертификатов для реальных, существующих в интернете доменов, что привело бы к серьёзным нарушениям безопасности.

Если вам нужен HTTPS для публичного домена на этапе разработки (например, для тестирования до запуска), следует использовать тестовые (staging) сертификаты от Let's Encrypt или другие инструменты, предназначенные для этого.

Заключение

Инструмент mkcert устраняет ключевую проблему современной веб-разработки — сложность настройки валидного HTTPS в локальной среде. Вместо многоэтапных процедур с OpenSSL и ручным импортом сертификатов, mkcert предлагает одноэтапное решение, которое автоматически интегрируется в систему безопасности вашего компьютера.

Преимущества:

• Минимальная настройка: Одна команда mkcert -install настраивает доверенный центр сертификации.
• Полная эмуляция продакшена: Браузеры отображают «зелёный замочек» без предупреждений.
• Универсальность: Кросс-платформенная работа с поддержкой Nginx, Apache, Caddy и встроенных серверов.
• Долгосрочное решение: Сертификаты не требуют регулярного обновления.

mkcert переводит HTTPS из категории инфраструктурной проблемы в разряд стандартного инструмента разработчика. Его внедрение в рабочий процесс позволяет сосредоточиться на создании функциональности, а не на решении задач конфигурации.

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