--- 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://.github.io/[repository]/` или `https:///` в зависимости от ваших настроек. Ваш сайт будет автоматически разворачиваться при каждом внесении изменений в ветке `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": "" } } ``` 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). ### Nginx Вот пример конфигурации блока сервера Nginx. Эта настройка включает сжатие gzip для общих текстовых ресурсов, правила обслуживания статических файлов вашего сайта VitePress с правильными заголовками кэширования и обработку параметра `cleanUrls: true`. ```nginx server { gzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; listen 80; server_name _; index index.html; location / { # расположение контента root /app; # точные совпадения -> обратные чистые URL-адреса -> папки -> не найдены try_files $uri $uri.html $uri/ =404; # несуществующие страницы error_page 404 /404.html; # папка без index.html вызывает ошибку 403 в этой настройке error_page 403 /404.html; # настройка заголовков кэширования # файлы в папке с ресурсами имеют хэши имён файлов location ~* ^/assets/ { expires 1y; add_header Cache-Control "public, immutable"; } } } ``` Эта конфигурация предполагает, что ваш собранный сайт VitePress находится в директории `/app`. При необходимости измените директиву `root`, если файлы вашего сайта расположены в другом месте. ::: warning Не используйте index.html по умолчанию Разрешение try_files не должно использовать index.html, как это делается в других приложениях Vue. Это может привести к недопустимому состоянию страницы. ::: Дополнительную информацию можно найти в официальной документации [Nginx](https://nginx.org/ru/docs/), а также в следующих обсуждениях: [#2837](https://github.com/vuejs/vitepress/discussions/2837), [#3235](https://github.com/vuejs/vitepress/issues/3235), а также в [блоге Mehdi Merah](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings).