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

На этой странице описано, как развернуть проект Rspress после завершения разработки. Развёртывание обычно включает:

• Сборку и предпросмотр продакшен-версии.
• Настройку префикса для статических ресурсов.
• Настройку базового пути проекта.
• Выбор платформы для развёртывания.

#Сборка и просмотр

Перед развёртыванием соберите проект для продакшена и выполните локальный предпросмотр, чтобы убедиться, что всё работает корректно. В проектах Rspress используйте следующие команды scripts:

{
  "scripts": {
    "build": "rspress build",
    "preview": "rspress preview"
  }
}

По умолчанию итоговый результат сборки записывается в директорию doc_build в корне проекта. Развёртывайте содержимое этой директории.

#Настройка префикса для статических ресурсов

Результат развёртывания можно разделить на две части: HTML-файлы и статические ресурсы. HTML-файлы — это страницы в выходной директории, которые развёртываются на сервере.

Статические ресурсы находятся в директории static внутри выходной директории. В ней содержатся JavaScript, CSS, изображения и другие ресурсы, необходимые сайту. Если вы хотите отдавать эти ресурсы через CDN вместо того, чтобы размещать их на том же сервере, что и HTML-файлы, настройте префикс статических ресурсов, чтобы HTML корректно ссылался на CDN-URL. Используйте builderConfig.output.assetPrefix:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  builderConfig: {
    output: {
      assetPrefix: 'https://cdn.com/',
    },
  },
});

После этого Rspress автоматически добавляет префикс к ссылкам на статические ресурсы в HTML:

<script src="https://cdn.com/static/js/app.123.js"></script>

#Настройка базового пути проекта

При развёртывании в подкаталог необходимо настроить параметр base. Например, если сайт будет развёрнут по адресу https://foo.github.io/bar/, установите base в "/bar/":

import { defineConfig } from '@rspress/core';

export default defineConfig({
  base: '/bar/',
});

Для получения более подробной информации см. справочник конфигурации base.

#Платформы для развёртывания

После завершения описанной выше настройки разверните результат на хостинг-платформе. Часто используются Zephyr, GitHub Pages, Netlify, Vercel, Kinsta и Zeabur. Далее рассмотрим несколько примеров.

#Развёртывание через Zephyr Cloud

Zephyr Cloud — это платформа для развёртывания без конфигурации, которая интегрируется напрямую в процесс сборки и обеспечивает глобальную доставку сайта через сеть серверов, расположенных ближе к пользователям.

#Как развернуть

Следуйте инструкциям плагина zephyr-rspress-plugin.

В процессе сборки ваш сайт документации Rspress разворачивается автоматически, и вы получаете URL для доступа к нему.

Zephyr Cloud обеспечивает оптимизацию ресурсов, глобальную CDN-дистрибуцию и автоматический откат для сайтов документации.

#Развёртывание через GitHub Actions

Если ваш проект размещён на GitHub, вы можете развернуть его с помощью GitHub Pages. GitHub Pages — это сервис статического хостинга от GitHub, поэтому вы можете развернуть сайт без собственного сервера.

#1. Создание workflow-файла

Создайте файл .github/workflows/deploy.yml в корне проекта со следующим содержимым:

name: Deploy Rspress site to Pages

on:
  push:
    branches: [main]

  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Not needed if lastUpdated is not enabled
      - uses: pnpm/action-setup@v3 # pnpm is optional but recommended, you can also use npm / yarn
        with:
          version: 8
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Install dependencies
        run: pnpm install
      - name: Build with Rspress
        run: |
          pnpm run build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: doc_build

  # Deployment job
  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

#2. Настройка GitHub Actions

В настройках репозитория откройте раздел Pages и выберите GitHub Actions в качестве источника развёртывания.

#3. Отправка кода в ветку main

При пуше кода в ветку main GitHub Actions автоматически запускает процесс развёртывания. Ход выполнения можно посмотреть во вкладке Actions. После завершения развёртывания сайт будет доступен по адресу https://<username>.github.io/<repository>/.

#Развёртывание через Netlify

Netlify — это платформа для развёртывания веб-приложений. Вы можете развернуть сайт Rspress на Netlify без собственного сервера.

#Базовая настройка

Чтобы развернуть проект на Netlify, импортируйте репозиторий из GitHub и настройте два параметра:

• Build command: команда сборки проекта, например npm run build.
• Publish directory: директория с результатом сборки, обычно doc_build.

Затем нажмите Deploy site, чтобы запустить развёртывание.

#Настройка собственного домена

Чтобы привязать собственный домен, настройте его в разделе Netlify Domain management. Подробнее см. в официальной документации Netlify.

#Развёртывание на хостинге статических сайтов Kinsta

Вы можете разместить свой сайт на Kinsta.

1. Войдите в систему или создайте аккаунт, чтобы открыть панель управления MyKinsta.

2. Авторизуйте Kinsta через ваш Git-провайдер.

3. В левом боковом меню выберите Static Sites и нажмите Add sites.

4. Выберите репозиторий и ветку, которые хотите развернуть.

5. В настройках сборки Kinsta пытается автоматически заполнить Build command, Node version и Publish directory. Если этого не произошло, используйте:

   • Build command: npm run build
   • Node version: 18.16.0
   • Publish directory: doc_build

6. Нажмите Create site.

#Развёртывание на Zeabur

Zeabur — это платформа для быстрого развёртывания сервисов. Она позволяет развернуть сайт Rspress без дополнительной настройки.

#Как развернуть

Сначала создайте аккаунт в Zeabur. Затем следуйте инструкциям, чтобы создать проект и установить GitHub-приложение, чтобы Zeabur получил доступ к вашему репозиторию Rspress.

Нажмите Deploy New Service и импортируйте репозиторий Rspress. Развёртывание начнётся автоматически, и Zeabur определит, что сайт собран с помощью Rspress.

Обычно развёртывание занимает около минуты. Также можно привязать бесплатный поддомен Zeabur или собственный домен к сайту.

#Устранение неполадок

#Страница показывает 404 после обновления

Если сайт нормально работает при навигации, но после обновления страницы появляется ошибка 404, см. раздел Страница показывает 404 после обновления в документации по SSG.