Развертывание 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 для неизвестных путей, со стандартной страницей ошибки nginx, а не 404.html сайта. Пользовательский Dockerfile для этой политики маршрутизации не требуется. Если ваш сервис всё ещё использует образ, собранный до исправления маршрутизации от сентября 2026 года, пересоберите его. Используйте статические маршруты и 404 только когда нужно своё поведение nginx, например собственная 404-страница.

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

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

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

Обновлено 21 октября 2026 г.