<span id="deploy-docusaurus-on-lizard" />

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

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

Начните с [полного примера исходного кода](https://github.com/lizard-build/docs/tree/main/_examples/docusaurus), который включает конфигурацию и файлы, используемые в этом рецепте.

<span id="prepare-the-site" />

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

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

| Параметр | Значение |
|---|---|
| Сборка | `npm run build` |
| Вывод | `build/` |
| Среда выполнения | nginx |
| Порт сервиса | `80` |

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

Выберите единую политику слеша в конце URL и проверьте полученные файлы. Оставьте каталог вывода по умолчанию, если не используете Dockerfile, копирующий ваш собственный каталог. [Руководство по развертыванию Docusaurus](https://docusaurus.io/docs/deployment) объясняет эти настройки фреймворка.

<span id="build-and-check-locally" />

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

```bash
npm ci
npm run build
npm run serve
```

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

<span id="deploy" />

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

После [настройки CLI](https://lizard.build/ru/docs/framework-guides#prepare-the-project):

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

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

```bash
lizard service show web --json
```

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

```js
url: 'https://YOUR_PUBLIC_HOST',
```

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

```bash
lizard up --service web --port 80
```


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

<span id="serve-inner-routes-and-missing-pages" />

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

Новые сборки Docusaurus отдают сгенерированные файлы маршрутов и возвращают HTTP 404 для неизвестных путей. Пользовательский Dockerfile для этой политики маршрутизации не требуется. Если ваш сервис всё ещё использует образ, собранный до исправления маршрутизации от сентября 2026 года, пересоберите его. Используйте [статические маршруты и 404](https://lizard.build/ru/docs/framework-guides/static-routing) только когда нужен пользовательский nginx-поведение.

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

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

См. [проверенные версии и результаты в облаке](https://lizard.build/ru/docs/framework-guides/validation) для проверок развертывания от 9 сентября 2026 года и их ограничений.