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

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

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

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

Для Markdown-файлов в docs/ оставьте эти скрипты в package.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.

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

npm ci
npm run docs:build
npm run docs:preview

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

Разверните

После настройки CLI выполните из директории, содержащей package.json, а не изнутри docs/:

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 как команду запуска сервиса.

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

Новые сборки VitePress разрешают маршруты без расширения к их сгенерированным файлам .html и возвращают HTTP 404 для несуществующих URL. Оставьте переопределения команд не заданными, чтобы использовать этот путь обнаружения. Пользовательский Dockerfile не нужен для стандартного вывода. См. статические маршруты и 404 для пользовательской маршрутизации.

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

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

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

Docusaurus Hugo