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

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

Lizard может собрать сайт документации VitePress и отдать сгенерированный HTML через nginx на порту `80`. Соотнесите npm-скрипт и выходную директорию с корнем вашей документации: `vitepress build docs` пишет в `docs/.vitepress/dist`, а `vitepress build` пишет в `.vitepress/dist`.

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

<span id="set-the-build-script" />

## Установите скрипт сборки

Для Markdown-файлов в `docs/` оставьте эти скрипты в `package.json`:

```json
{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}
```

| Настройка | Значение в этом руководстве |
|---|---|
| Сборка | `npm run docs:build` |
| Корень документации | `docs/` |
| Выход | `docs/.vitepress/dist/` |
| Продакшн-сервер | nginx |
| Порт сервиса | `80` |

Детектор находит скрипт, содержащий `vitepress build`, и использует его аргумент root. Держите этот скрипт прямым и однозначным. Обёртки оболочки, несколько подходящих скриптов или пользовательский `outDir` требуют явной конфигурации сборки или Dockerfile.

<span id="check-the-site-locally" />

## Проверьте сайт локально

```bash
npm ci
npm run docs:build
npm run docs:preview
```

Проверьте внутреннюю страницу Markdown и ассет. С `cleanUrls: true` VitePress ссылается на маршруты без расширения; продакшн-сервер должен разрешать эти URL к сгенерированным HTML-файлам. Установите `base` на фактический префикс пути или `/` для корня домена. См. [развертывание VitePress](https://vitepress.dev/guide/deploy).

<span id="deploy" />

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

После [настройки CLI](https://lizard.build/ru/docs/framework-guides#prepare-the-project) выполните из директории, содержащей `package.json`, а не изнутри `docs/`:

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

Включите конфигурацию VitePress, Markdown, исходные ассеты, манифест пакета и lockfile. Исключите локальные зависимости, сгенерированный вывод, кэши и секреты. Не устанавливайте `vitepress dev` или `vitepress preview` как команду запуска сервиса.

<span id="check-clean-routes-and-http-status" />

## Проверьте чистые маршруты и HTTP-статус

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

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

Если сборка сообщает `Missing script: build`, проверьте, что выбранный путь использует детектор VitePress, и что никакое переопределение команды сервиса его не заменяет. Если сборка прошла успешно, но nginx не отдаёт документацию, сравните docs root скрипта со скопированной выходной директорией. Пересоберите после изменений контента или конфигурации.

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