vitepress/docs/ru/guide/deploy.md

---
outline: deep
---

# Развёртывание вашего сайта VitePress {#deploy-your-vitepress-site}

Следующие руководства основаны на некоторых общих предположениях:

- Сайт VitePress находится в директории `docs` вашего проекта.
- Вы используете выходной каталог сборки по умолчанию (`.vitepress/dist`).
- VitePress установлен как локальная зависимость в вашем проекте, и вы установили следующие скрипты в вашем `package.json`:

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

## Создание и локальное тестирование {#build-and-test-locally}

1. Выполните эту команду, чтобы собрать документацию:

   ```sh
   $ npm run docs:build
   ```

2. После сборки просмотрите её локально, запустив команду:

   ```sh
   $ npm run docs:preview
   ```

   Команда `preview` загрузит локальный статический веб-сервер, который будет обслуживать выходной каталог `.vitepress/dist` по адресу `http://localhost:4173`. Вы можете использовать это, чтобы убедиться, что всё выглядит хорошо, прежде чем отправлять в производство.

3. Вы можете настроить порт сервера, передав `--port` в качестве аргумента.

   ```json
   {
     "scripts": {
       "docs:preview": "vitepress preview docs --port 8080"
     }
   }
   ```

   Теперь метод `docs:preview` запустит сервер по адресу `http://localhost:8080`.

## Установка публичного базового пути {#setting-a-public-base-path}

По умолчанию предполагается, что сайт будет развёрнут по корневому пути домена (`/`). Если ваш сайт будет обслуживаться по подпути, например, `https://mywebsite.com/blog/`, то в конфигурации VitePress необходимо установить для опции [`base`](../reference/site-config#base) значение `'/blog/'`.

**Пример:** Если вы используете Github (или GitLab) Pages и развёртываете на `user.github.io/repo/`, то установите `base` на `/repo/`.

## Заголовки кэша HTTP {#http-cache-headers}

Если вы контролируете HTTP-заголовки на своем рабочем сервере, вы можете настроить заголовки `cache-control` для достижения лучшей производительности при повторных посещениях.

В производственной сборке используются хэшированные имена файлов для статических ресурсов (JavaScript, CSS и другие импортированные ресурсы, не находящиеся в `public`). Если вы просмотрите предварительную версию с помощью сетевой вкладки devtools вашего браузера, вы увидите файлы типа `app.4f283b18.js`.

Этот хэш `4f283b18` генерируется из содержимого этого файла. Один и тот же хэшированный URL гарантированно обслуживает одно и то же содержимое файла — если содержимое меняется, то и URL тоже. Это означает, что вы можете смело использовать самые сильные заголовки кэша для этих файлов. Все такие файлы будут помещены в каталог `assets/` в выходном каталоге, поэтому вы можете настроить для них следующий заголовок:

```
Cache-Control: max-age=31536000,immutable
```

::: details Пример файла Netlify `_headers`

```
/assets/*
  cache-control: max-age=31536000
  cache-control: immutable
```

Примечание: файл `_headers` должен быть помещён в [директорию `public`](./asset-handling#the-public-directory) — в нашем случае `docs/public/_headers` — так, чтобы он был скопирован в выходной каталог.

[Netlify custom headers documentation](https://docs.netlify.com/routing/headers/)

:::

::: details Пример конфигурации Vercel в файле `vercel.json`

```json
{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000, immutable"
        }
      ]
    }
  ]
}
```

Примечание: Файл `vercel.json` должен быть помещен в корень вашего **репозитория**.

[Документация Vercel по конфигурации заголовков](https://vercel.com/docs/concepts/projects/project-configuration#headers)

:::

## Руководства по платформам {#platform-guides}

### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render {#netlify-vercel-cloudflare-pages-aws-amplify-render}

Создайте новый проект и измените эти настройки с помощью панели управления:

- **Build Command:** `npm run docs:build`
- **Output Directory:** `docs/.vitepress/dist`
- **Node Version:** `18` (или выше)

::: warning ПРЕДУПРЕЖДЕНИЕ
Не включайте такие опции, как _Auto Minify_ для HTML-кода. Он удалит из вывода комментарии, которые имеют значение для Vue. При их удалении могут возникать ошибки несоответствия гидратации.
:::

### GitHub Pages {#github-pages}

1. Создайте файл с именем `deploy.yml` в директории `.github/workflows` вашего проекта с примерно таким содержанием:

   ```yaml
   # Пример рабочего процесса для создания и развёртывания сайта VitePress на GitHub Pages
   #
   name: Deploy VitePress site to Pages

   on:
     # Выполняется при пушах, направленных в ветку `main`. Измените это значение на `master`, если вы
     # используете ветку `master` в качестве ветки по умолчанию.
     push:
       branches: [main]

     # Позволяет запустить этот рабочий процесс вручную на вкладке «Actions».
     workflow_dispatch:

   # Устанавливает разрешения GITHUB_TOKEN, чтобы разрешить развёртывание на страницах GitHub.
   permissions:
     contents: read
     pages: write
     id-token: write

   # Разрешите только одно одновременное развёртывание, пропуская запуски, стоящие в очереди.
   # Однако НЕ отменяйте текущие запуски, поскольку мы хотим дать возможность завершить производственные развёртывания.
   concurrency:
     group: pages
     cancel-in-progress: false

   jobs:
     # Сборка
     build:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout
           uses: actions/checkout@v4
           with:
             fetch-depth: 0 # Не требуется, если функция lastUpdated не включена
         # - uses: pnpm/action-setup@v3 # Раскомментируйте, если вы используете pnpm
         # - uses: oven-sh/setup-bun@v1 # Раскомментируйте, если вы используете Bun
         - name: Setup Node
           uses: actions/setup-node@v4
           with:
             node-version: 20
             cache: npm # или pnpm / yarn
         - name: Setup Pages
           uses: actions/configure-pages@v4
         - name: Install dependencies
           run: npm ci # или pnpm install / yarn install / bun install
         - name: Build with VitePress
           run: npm run docs:build # или pnpm docs:build / yarn docs:build / bun run docs:build
         - name: Upload artifact
           uses: actions/upload-pages-artifact@v3
           with:
             path: docs/.vitepress/dist

     # Развёртывание
     deploy:
       environment:
         name: github-pages
         url: ${{ steps.deployment.outputs.page_url }}
       needs: build
       runs-on: ubuntu-latest
       name: Deploy
       steps:
         - name: Deploy to GitHub Pages
           id: deployment
           uses: actions/deploy-pages@v4
   ```

   ::: warning ПРЕДУПРЕЖДЕНИЕ
   Убедитесь, что опция `base` в вашем VitePress настроена правильно. Дополнительные сведения см. в секции [Установка публичного базового пути](#setting-a-public-base-path).
   :::

2. В настройках вашего репозитория в разделе «Pages» выберите пункт меню «GitHub Actions» в секции «Build and deployment > Source».

3. Внесите свои изменения в ветку `main` и дождитесь завершения процесса GitHub Actions. Вы должны увидеть, что ваш сайт развёрнут по адресу `https://<username>.github.io/[repository]/` или `https://<custom-domain>/` в зависимости от ваших настроек. Ваш сайт будет автоматически разворачиваться при каждом внесении изменений в ветке `main`.

### GitLab Pages {#gitlab-pages}

1. Установите `outDir` в конфигурации VitePress на `../public`. Настройте опцию `base` на `'/<репозиторий>/'`, если вы хотите развернуть ваш проект по адресу на `https://<имя пользователя>.gitlab.io/<репозиторий>/`.

2. Создайте файл с именем `.gitlab-ci.yml` в корне вашего проекта с приведённым ниже содержимым. Это позволит создавать и развёртывать ваш сайт каждый раз, когда вы вносите изменения в его содержимое:

   ```yaml
   image: node:18
   pages:
     cache:
       paths:
         - node_modules/
     script:
       # - apk add git # Отметьте это, если вы используете небольшие докер-образы, такие как alpine, и у вас включен lastUpdated
       - npm install
       - npm run docs:build
     artifacts:
       paths:
         - public
     only:
       - main
   ```

### Статические веб-приложения Azure {#azure-static-web-apps}

1. Следуйте [официальной документации](https://docs.microsoft.com/ru-ru/azure/static-web-apps/build-configuration).

2. Установите эти значения в вашем конфигурационном файле (и удалите те, которые вам не нужны, например, `api_location`):

   - **`app_location`**: `/`
   - **`output_location`**: `docs/.vitepress/dist`
   - **`app_build_command`**: `npm run docs:build`

### Firebase {#firebase}

1. Создайте `firebase.json` и `.firebaserc` в корне вашего проекта:

   `firebase.json`:

   ```json
   {
     "hosting": {
       "public": "docs/.vitepress/dist",
       "ignore": []
     }
   }
   ```

   `.firebaserc`:

   ```json
   {
     "projects": {
       "default": "<YOUR_FIREBASE_ID>"
     }
   }
   ```

2. После запуска `npm run docs:build` выполните эту команду для развёртывания:

   ```sh
   firebase deploy
   ```

### Surge {#surge}

1. После запуска `npm run docs:build` выполните эту команду для развёртывания:

   ```sh
   npx surge docs/.vitepress/dist
   ```

### Heroku {#heroku}

1. Следуйте документации и руководству, приведённому в [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static).

2. Создайте файл `static.json` в корне вашего проекта со следующим содержимым:

   ```json
   {
     "root": "docs/.vitepress/dist"
   }
   ```

### Edgio {#edgio}

См. [Создание и развёртывание приложения VitePress в Edgio](https://docs.edg.io/applications/v6/sites_frameworks/getting_started/vitepress).

### Хостинг статических файлов Kinsta {#kinsta-static-site-hosting}

Вы можете развернуть свой сайт Vitepress на [Kinsta](https://kinsta.com/static-site-hosting/), следуя этим [инструкциям](https://kinsta.com/docs/vitepress-static-site-example/).

### Stormkit

Вы можете развернуть свой проект VitePress на [Stormkit](https://www.stormkit.io), следуя следующим [инструкциям](https://stormkit.io/blog/how-to-deploy-vitepress).