Развертывание Docusaurus на Lizard

Соберите Docusaurus на Lizard и раздавайте сгенерированный каталог build/ через nginx на порту 80. Продакшн-развертывание отдаёт статические файлы; оно не запускает сервер разработки docusaurus start.

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

Подготовка сайта

Выполните из каталога Docusaurus, содержащего package.json, его lock-файл и docusaurus.config.*. Оставьте @docusaurus/core в зависимостях и скрипт сборки, запускающий docusaurus build.

Задайте url в конфигурации Docusaurus как предполагаемый публичный адрес сайта, а baseUrl — как путь, по которому он будет работать. Для сайта в корне домена baseUrl равен /. Как только вы узнаете окончательное имя хоста, пересоберите с этим хостом, чтобы сгенерированные канонические URL и записи в карте сайта использовали его.

Выберите единую политику слеша в конце URL и проверьте полученные файлы. Оставьте каталог вывода по умолчанию, если не используете Dockerfile, копирующий ваш собственный каталог. Руководство по развертыванию Docusaurus объясняет эти настройки фреймворка.

Локальная сборка и проверка

npm ci
npm run build
npm run serve

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

Развертывание

После настройки CLI:

lizard init --name docusaurus-docs
lizard add --service web
lizard up --service web --port 80
lizard logs --build --service web --json
lizard ps --json

Если используете сгенерированное имя хоста, прочитайте его после первого развертывания:

lizard service show web --json

Задайте url в docusaurus.config.js этому имени хоста:

url: 'https://YOUR_PUBLIC_HOST',

Загрузите изменённую конфигурацию, чтобы сборка использовала публичный URL:

lizard up --service web --port 80

Закоммитьте исходный код, плагины, конфигурацию и lock-файл. Исключите файлы node_modules/, build/, .docusaurus/ и .env из загрузки. Оставьте переопределения команды сервиса не заданными, чтобы использовался путь автоопределения Docusaurus.

Обслуживание внутренних маршрутов и отсутствующих страниц

Новые сборки Docusaurus отдают сгенерированные файлы маршрутов и возвращают HTTP 404 для неизвестных путей. Пользовательский Dockerfile для этой политики маршрутизации не требуется. Если ваш сервис всё ещё использует образ, собранный до исправления маршрутизации от сентября 2026 года, пересоберите его. Используйте статические маршруты и 404 только когда нужен пользовательский nginx-поведение.

После развертывания запросите напрямую вложенный URL документации, обновите страницу и проверьте статус несуществующего URL. Также проверьте канонический URL и карту сайта на конечном имени хоста. Видимая страница ошибки с HTTP 200 всё равно является мягким 404.

Если ресурсы отсутствуют, сравните их URL с baseUrl. Если внутренний маршрут возвращает главную страницу, изучите структуру сгенерированных файлов и правила nginx. Если после изменения переменной окружения или Markdown-файла остаётся старый контент, убедитесь, что новая сборка действительно завершилась; статический HTML меняется только при сборке.

См. проверенные версии и результаты в облаке для проверок развертывания от 9 сентября 2026 года и их ограничений.