From 4ace3c546087263553c87315f287affb6a406c4d Mon Sep 17 00:00:00 2001 From: Bugo Date: Fri, 22 Mar 2024 08:32:01 +0500 Subject: [PATCH] Translate guide/deploy.md --- docs/ru/guide/deploy.md | 289 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 docs/ru/guide/deploy.md diff --git a/docs/ru/guide/deploy.md b/docs/ru/guide/deploy.md new file mode 100644 index 00000000..3879b047 --- /dev/null +++ b/docs/ru/guide/deploy.md @@ -0,0 +1,289 @@ +--- +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/guides/vitepress). + +### Хостинг статических файлов Kinsta {#kinsta-static-site-hosting} + +Вы можете развернуть свой сайт Vitepress на [Kinsta](https://kinsta.com/static-site-hosting/), следуя этим [инструкциям](https://kinsta.com/docs/vitepress-static-site-example/).