> For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt.

# Генерация статического сайта (SSG)

## Что такое SSG

SSG (Static Site Generation) — это способ предварительной генерации страниц в виде HTML-файлов на этапе **сборки**, а не во время обращения пользователя к сайту.

**Преимущества SSG:**

- **Быстрее отображается первый контент**: пользователю не нужно ждать загрузки и выполнения JavaScript — страница полностью видна сразу после загрузки HTML-файла браузером
- **Дружелюбно к SEO**: поисковые роботы могут напрямую получить готовый HTML-контент
- **Простое развёртывание**: на выходе получаются статические файлы, которые можно разместить на любом сервисе статического хостинга без сервера.

По умолчанию в Rspress включена SSG. При выполнении команды `rspress build` каждая страница предварительно рендерится в HTML-файл с полным содержимым. В следующих разделах объясняется, как работает SSG.

## Различия между режимами разработки и сборки \{#differences-between-dev-and-build}

Rspress использует разные стратегии рендеринга в зависимости от режима: в процессе разработки применяется Client-Side Rendering (CSR) для более комфортной работы, а в продакшен-сборке по умолчанию используется SSG для достижения оптимальной производительности.

| Аспект                    | Режим разработки                    | Режим сборки (Продакшен)                                |
| ------------------------- | ----------------------------------- | ------------------------------------------------------- |
| Команда                   | `rspress dev`                       | `rspress build`                                         |
| Рендеринг                 | Чистый CSR (Client-Side Rendering)  | SSG (по умолчанию) или CSR                              |
| Предварительный рендеринг | Отсутствует                         | Предварительно рендерит все страницы при включённом SSG |
| Основная цель             | Отладка, горячая перезагрузка (HMR) | Производительность, SEO                                 |
| Способ просмотра          | Прямой доступ к dev-серверу         | `rspress preview`                                       |

### Режим разработки

```bash
rspress dev
```

В режиме разработки используется **чистый рендеринг на стороне клиента (CSR)** без предварительного рендеринга. Это позволяет максимально ускорить итерации и обеспечить полноценную работу Hot Module Replacement (HMR — горячая перезагрузка модулей).

:::tip
Если ваш код работает в режиме разработки, но выдаёт ошибки в режиме сборки, обычно это связано с тем, что SSG выполняет рендеринг в среде Node.js и не имеет доступа к браузерным API, таким как `window` или `document`. См. раздел «[Распространённые проблемы и их решения](#common-issues-and-solutions)» ниже.
:::

### Режим сборки

```bash
rspress build
```

Режим сборки включает SSG по умолчанию. Вы можете управлять этим поведением через конфигурацию [`ssg`](#configuration):

- `ssg: true` (по умолчанию): включает SSG. Во время сборки Rspress выполняет рендеринг React-компонентов в среде Node.js, преобразуя каждую страницу в полноценный HTML-файл с готовым содержимым.
- `ssg: false`: отключает SSG и включает CSR. Сгенерированный HTML содержит пустой контейнер страницы, ожидающий рендеринга на стороне клиента. Это не влияет на SSG-MD, который управляется независимо через `llms`.

**После выполнения сборки:**

- **Локальный просмотр**: используйте команду `rspress preview`, чтобы запустить локальный статический сервер и просмотреть результат сборки.

  ```bash
  rspress preview
  ```

- **Развёртывание на сервере**: Разместите содержимое директории `doc_build` на любом сервисе статического хостинга (GitHub Pages, Netlify, Vercel и т. д.)

## SSG vs CSR — результат сборки

### Структура выходной директории

Независимо от того, используется режим SSG или CSR, структура выходной директории остаётся одинаковой:

```tree
doc_build/
├── static/
│   ├── js/
│   │   ├── main.[hash].js
│   │   └── async/
│   └── css/
│       └── main.[hash].css
├── index.html
├── 404.html
├── guide/
│   └── getting-started.html
└── api/
    └── config.html
```

Файл `404.html` автоматически генерируется Rspress для обработки несуществующих маршрутов. Этот файл играет важную роль при развёртывании в формате SPA, подробности см. в разделе [«Страница показывает 404 после обновления»](#refresh-404).

### Различия в содержимом HTML

Основное различие между двумя режимами заключается в содержимом генерируемых HTML-файлов:

**HTML в режиме SSG** (полностью предрендеренное содержимое):

```html
<body>
  <div id="__rspress_root">
    <!-- полностью предрендеренный контент страницы -->
    <nav>...</nav>
    <main>
      <article>
        <h1>Первые шаги</h1>
        <p>Добро пожаловать в Rspress...</p>
      </article>
    </main>
  </div>
  <script src="/static/js/main.[hash].js"></script>
</body>
```

**HTML в режиме CSR** (только пустой контейнер, ожидает рендеринга JavaScript):

```html
<body>
  <div id="__rspress_root"></div>
  <script src="/static/js/main.[hash].js"></script>
</body>
```

### Различия в процессе загрузки

**Процесс загрузки в режиме SSG:**

1. Браузер загружает HTML → Пользователь **сразу видит полностью готовый контент**
2. JavaScript завершает загрузку → React выполняет гидратацию, привязывает обработчики событий и интерактивность
3. Последующая навигация → Режим SPA, рендеринг на стороне клиента

**Процесс загрузки в режиме CSR:**

1. Браузер загружает HTML → Пользователь видит **пустую страницу**
2. JavaScript завершает загрузку → React рендерит содержимое страницы
3. Последующая навигация → Режим SPA, рендеринг на стороне клиента

## Распространённые проблемы и их решения \{#common-issues-and-solutions}

### `window is not defined` / `document is not defined`

**Причина**: SSG выполняет рендеринг страниц в среде Node.js, где отсутствуют глобальные объекты браузера, такие как `window` и `document`.

**Решения:**

1. **Используйте [`BrowserOnly`](/rspress-russian/ui/runtime-components/browser-only.md) для рендеринга только в браузере**: Оберните код, который не может выполняться во время SSG, в функцию.

   ```tsx
   import { BrowserOnly } from '@rspress/core/runtime';

   function MyComponent(props) {
     return (
       <BrowserOnly fallback={<div>Загрузка...</div>}>
         {async () => {
           const { LibComponent } =
             await import('some-lib-that-accesses-window');
           return <LibComponent {...props} />;
         }}
       </BrowserOnly>
     );
   }
   ```

   `children` компонента должны быть функцией, а не JSX. Иначе такие выражения как `window.location.href` будут выполняться во время серверной генерации страниц (SSG).

2. **Используйте `useEffect` для отложенного выполнения**: Помещайте обращения к браузерным API внутрь `useEffect`, чтобы они выполнялись только на стороне клиента.

   ```tsx
   import { useEffect, useState } from 'react';

   function MyComponent() {
     const [width, setWidth] = useState(0);

     useEffect(() => {
       // Запускается только на клиенте
       setWidth(window.innerWidth);
     }, []);

     return <div>Ширина окна: {width}</div>;
   }
   ```

3. **Проверка окружения**: Проверяйте среду перед обращением к браузерным API

   ```tsx
   if (typeof window !== 'undefined') {
     // Среда браузера
     console.log(window.location.href);
   }
   ```

4. **Динамический импорт в `useEffect`**: Для сторонних библиотек, которые зависят от браузерных API, используйте динамический импорт в `useEffect`

   ```tsx
   import { useEffect, useState } from 'react';

   function MyComponent() {
     const [Editor, setEditor] = useState(null);

     useEffect(() => {
       import('some-browser-only-library').then(mod => {
         setEditor(() => mod.default);
       });
     }, []);

     if (!Editor) return <div>Загрузка...</div>;
     return <Editor />;
   }
   ```

### Несоответствие при гидратации

**Причина**: Содержимое HTML, сгенерированное на сервере, не совпадает с тем, что React впервые рендерит на клиенте. Во время процесса гидратации React проверяет согласованность, и любое расхождение вызывает предупреждения или ошибки.

**Типичные ситуации, приводящие к проблеме**:

- Использование `Date.now()` или случайных чисел (`Math.random()`)
- Рендеринг разного контента в зависимости от свойств объекта `window` (например, `window.innerWidth`, `window.matchMedia`)
- Использование данных, доступных только на клиенте (например, `localStorage`, `sessionStorage`)

**Решение**: Убедитесь, что результат первого рендера полностью одинаков на сервере и на клиенте. Для любого контента, который должен динамически изменяться на стороне клиента, используйте `useEffect` — обновляйте состояние уже после завершения гидратации.

```tsx
import { useEffect, useState } from 'react';

function MyComponent() {
  // Первый рендер использует значение по умолчанию для согласованности между сервером и клиентом
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    // Читаем значение из localStorage уже после завершения гидратации
    const savedTheme = localStorage.getItem('theme');
    if (savedTheme) {
      setTheme(savedTheme);
    }
  }, []);

  return <div className={theme}>...</div>;
}
```

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

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

**Причина**: При обновлении страницы или прямом переходе по URL запрос отправляется на сервер, однако сервер может не иметь соответствующего файла по этому пути (особенно это касается некоторых сервисов статического хостинга).

**Решение**: Большинство сервисов статического хостинга, таких как GitHub Pages, Netlify и Vercel, по умолчанию используют `404.html` для обработки несовпавших маршрутов и не требуют дополнительной настройки. Если ваш сервер не делает этого автоматически, настройте его так, чтобы он перенаправлял все несовпавшие запросы на `404.html`. Сгенерированный Rspress файл `404.html` содержит полный код приложения, поэтому может обрабатывать маршрутизацию на стороне клиента и отображать правильную страницу.

Если ваш хостинг поддерживает перенаправления в стиле Netlify, вы можете использовать файл `_redirects` следующего вида:

```txt title="docs/public/_redirects"
/*    /404.html   200
```

## Конфигурация \{#configuration}

Управлять включением SSG можно с помощью параметра `ssg`:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  ssg: true, // значение по умолчанию, SSG включен
});
```

Если у вашего сайта особые требования, вы можете отключить SSG, сохранив генерацию Markdown:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  ssg: false, // Отключаем SSG, используем CSR
});
```

:::warning Предупреждение
Будьте осторожны при отключении SSG — вы потеряете преимущества быстрого отображения первого контента (First Contentful Paint) и улучшенной индексации поисковыми системами (SEO).
:::

## Пользовательский HTML-контент

Чтобы добавить собственные HTML-теги, например мета-теги, код аналитики, скрипты или стили, см. раздел [Настройка тегов head](/rspress-russian/guide/advanced/custom-head.md).
