﻿---
title: "Руководство 6: дать читателям возможность комментировать"
description: "Настройка репозитория Giscus, комментарии статей и заметок, mapping, общие обсуждения переводов, параметры и устранение ошибок."
url: "https://demo.anglefeint.com/ru/blog/starter-guide-4-giscus-comments/"
language: "ru"
author: "Anglefeint"
published: "2026-11-10T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# Руководство 6: дать читателям возможность комментировать

Это руководство 6 из 8. [Порядок всех руководств](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/#tutorial-order) · [Справочник настроек](https://demo.anglefeint.com/ru/blog/config-reference/).

Anglefeint использует Giscus для комментариев, по умолчанию отключённых. Статьи и заметки включаются отдельно. Комментарии и реакции хранятся в настроенных GitHub Discussions; отдельная база данных статическому блогу не нужна.

Один раз настройте репозиторий и решите, делить ли обсуждения переводов. Изменять шаблон статьи или вставлять script в каждую статью не требуется.

## 1\. Подготовьте репозиторий GitHub и категорию

Откройте [страницу настройки Giscus](https://giscus.app/zh-CN) и выполните её проверки:

1.  Выберите свой публичный репозиторий GitHub для комментариев: репозиторий блога или отдельный.
2.  Включите Discussions.
3.  Установите приложение Giscus и предоставьте ему доступ к репозиторию.
4.  Выберите категорию и сохраните созданные данные репозитория и категории.

Страница создаёт script, но теме нужны только значения полей:

| Атрибут Giscus | Поле темы |
| --- | --- |
| `data-repo` | `theme.comments.repo`, например `yourname/your-repository` |
| `data-repo-id` | `theme.comments.repoId`, ID репозитория, не название |
| `data-category` | `theme.comments.category`, настоящее название категории |
| `data-category-id` | `theme.comments.categoryId`, ID категории, не название |

Не используйте пример ID, URL репозитория или имя пользователя вместо настоящего ID. Категория не обязательно Announcements: укажите выбранное название и соответствующий ID. Не нужны npm-пакет Giscus, GitHub token или пароль.

Это внешний сервис: страница должна подключаться к Giscus и GitHub. Посетителю для комментария нужна авторизация GitHub; можно участвовать и непосредственно в GitHub Discussion. Тема не предоставляет анонимные комментарии. Поведение сервиса определяет [официальная документация Giscus](https://giscus.app/zh-CN).

## 2\. Сначала включите комментарии обычных статей

Объедините с существующим `defineThemeConfig({...})` в `src/site.config.ts`:

```ts
theme: {
  comments: {
    enabled: true,
    repo: 'yourname/your-repository',
    repoId: 'REPLACE_WITH_REPO_ID',
    category: 'Announcements',
    categoryId: 'REPLACE_WITH_CATEGORY_ID',
    mapping: 'pathname',
    lang: '',
  },
},
```

Замените аккаунт, репозиторий, категорию и оба ID. В существующих `theme`/`comments` меняйте поля с сохранением остальных настроек, не создавайте повторные объекты.

Пример включает комментарии статей и связывает обсуждения по пути URL. `/zh/blog/my-first-post/` и `/en/blog/my-first-post/` — разные пути и по умолчанию разные обсуждения. `shareAcrossLocales` по умолчанию `false`. Если раньше он был включён, восстановите mapping по инструкции ниже: одного примера недостаточно.

Компонент статьи выводится только при включённых комментариях и четырёх заполненных полях репозитория/категории. Без них область может отсутствовать. Заполнители обычно проходят локальную проверку непустоты, но не подтверждают удалённую настройку. Переключателя frontmatter для отдельной статьи нет: `comments: false` одну статью не отключает.

`lang: ''` примера следует языку статьи. Настоящий стандарт темы — фиксированный `lang: 'en'`, поэтому для следования странице явно очистите поле. `zh` соответствует `zh-CN`, `zh-hant` — `zh-TW`, `pt-br` — `pt`. Это меняет интерфейс, не переводит комментарии посетителей.

## 3\. Убедитесь в настоящем подключении

Сохраните и откройте статью в локальном dev, найдите область комментариев внизу. Проверьте репозиторий обсуждения, вход, комментарии и реакции. Пустое обсуждение при первом открытии не означает сбой: Giscus может создать его при первом комментарии или реакции, а не сразу при просмотре.

Перед публикацией остановите dev и выполните:

```bash
npm run doctor
npm run preview
```

doctor включает проверки и сборку; после успеха сразу повторять build не нужно. preview показывает локальную сборку, не публикует сайт. Для настоящего сайта нужно повторное размещение. Успешная сборка подтверждает локальную конфигурацию и создание страниц, но не заменяет браузерную проверку прав реального репозитория и связи с сервисом.

Статьи используют `loading: 'lazy'` по умолчанию. Это режим iframe Giscus, а не ожидание прокрутки перед выводом script: статья выводит асинхронный скрипт Giscus. В отличие от неё, окно заметки загружает клиент после кнопки комментариев.

Типы, значения и примеры всех параметров — в [справочнике Giscus](https://demo.anglefeint.com/ru/blog/config-comments/#connection). Для существующих комментариев особенно проверьте mapping и ограничения общего обсуждения.

## 4\. Выберите связь статьи с обсуждением

Обычно оставьте `pathname`. Перед изменением изучите основу сопоставления, особенно если комментарии уже есть:

| `mapping` | Основа и ограничения |
| --- | --- |
| `'pathname'` | Путь URL без домена; смена пути может выбрать другое обсуждение |
| `'url'` | Полный URL, поэтому и смена домена может изменить связь |
| `'title'` | title вкладки; изменение заголовка статьи или сайта может повлиять |
| `'og:title'` | Заголовок Open Graph страницы |
| `'specific'` | Фиксированный `term`; вне общего режима должен быть непустым |
| `'number'` | Номер существующего discussion из `number`, не issue; автоматического создания нет |

Поиск обсуждения выполняет Giscus, локальной базы комментариев тема не создаёт. `strict: '1'` уменьшает нечёткие совпадения похожих названий, по умолчанию `'0'`.

Вне общего режима `term` и `number` глобальны для всех комментариев. `specific` с фиксированным term заставит все использующие его статьи искать одно обсуждение; `number` тоже указывает один номер. Они не распределяют отдельные обсуждения автоматически.

При включённых комментариях тема проверяет: term для `specific` непустой после удаления пробелов; `number` — строка положительного целого, например `'42'`, не число `42`, `'0'` или дробь. Ошибочные параметры останавливают проверку и могут блокировать dev/build.

## 5\. Объедините комментарии переводов одной статьи

Чтобы китайский и английский переводы делили обсуждение, а разные статьи были независимы, сохраните настоящие поля репозитория/категории и объедините mapping так:

```ts
theme: {
  comments: {
    // Сохраните enabled: true и свои значения repo, repoId, category и categoryId.
    shareAcrossLocales: true,
    mapping: 'specific',
    term: '',
    number: '',
    strict: '1',
    lang: '',
  },
},
```

Общий режим требует specific, пустых term и number и строкового strict `'1'`. Пустой term намеренный: страница подставляет полный slug без языкового каталога, а не общий фиксированный термин.

Например, `src/content/blog/zh/my-first-post.md` и `src/content/blog/en/my-first-post.md` используют `my-first-post`. Вложенные `guides/setup` и `other/setup` сохраняют полный путь и остаются разными обсуждениями. Переводам нужен одинаковый slug; сходство заголовков или текста не используется.

При включённых общем режиме и комментариях неправильный mapping, непустые term/number или strict не `'1'` вызывают явную ошибку. Стандартные маршруты передают slug; собственная страница с BlogPost тоже должна передать действительный articleSlug. Интерфейс определяется lang, текст комментариев не переводится.

Проверяйте два перевода одной статьи и другую статью: первые два должны делить обсуждение, третья — нет. Один язык интерфейса или внешний вид формы не подтверждают общность.

### Что делать с существующими комментариями?

Тема не объединяет, не переносит и не удаляет обсуждения. После включения общего режима выбранное обсуждение может измениться: старые комментарии остаются в GitHub, но не видны через новую связь.

До смены сохраните repo, category, mapping, term, number и strict. Для восстановления задайте `shareAcrossLocales: false` и верните исходные значения. Простое отключение общего режима с пустым term в specific вызовет ошибку. Если нужна уборка обсуждений, сначала проверьте данные и связи в GitHub: автоматической миграции нет.

## 6\. Комментарии заметок включаются отдельно

Только для заметок заполните ту же группу репозитория/категории и задайте:

```ts
theme: {
  fragments: {
    enabled: true,
    comments: { enabled: true },
  },
  comments: {
    enabled: false,
    repo: 'yourname/your-repository',
    repoId: 'REPLACE_WITH_REPO_ID',
    category: 'Announcements',
    categoryId: 'REPLACE_WITH_CATEGORY_ID',
  },
},
```

`theme.comments.enabled: false` отключает лишь статьи; заметки управляются `theme.fragments.comments.enabled`. Если статьи тоже нужны, сохраните true; ради заметок менять их mapping не нужно.

Заметки используют фиксированные specific, строгое совпадение и `fragment/<id>`, не используют mapping, term, number, shareAcrossLocales и фиксированный lang статей. Интерфейс следует странице, переводы с одним ID делят обсуждение. Реакции, цветовая тема, положение поля и другие общие параметры используются совместно. Включённые заметки без четырёх полей репозитория/категории сразу вызывают ошибку конфигурации.

Клиент загружается при первом щелчке комментариев карточки. Закрытие сохраняет экземпляр для повторного открытия и переключения заметок. При ошибке или ожидании примерно 15 секунд предлагается повтор. Подсказка загрузки не подтверждает подключение. Правила публикации, ID и ссылок — в [руководстве заметок](https://demo.anglefeint.com/ru/blog/starter-guide-5-fragments/).

## По необходимости: отображение и загрузка

Все поля ниже находятся в `theme.comments`; обычно достаточно стандартных значений.

| Поле | По умолчанию в теме | Назначение |
| --- | --- | --- |
| `reactionsEnabled` | `'1'` | Реакции на основную запись discussion; `'0'` выключает |
| `inputPosition` | `'bottom'` | Положение формы: `'top'`/`'bottom'` |
| `theme` | `'dark'` | Цветовой идентификатор Giscus из его страницы настройки; не переключает тему блога |
| `strict` | `'0'` | Строгое совпадение статьи; общий режим и заметки принудительно `'1'` |
| `emitMetadata` | `'0'` | Отправка метаданных обсуждения родительской странице, не метаданные публикации; для готовности заметок включается принудительно |
| `lang` | `'en'` | Фиксированный язык интерфейса статей; `''` следует странице, заметки всегда следуют странице |
| `loading` | `'lazy'` | iframe статьи `'lazy'`/`'eager'`; открытое окно заметок использует eager |
| `crossorigin` | `'anonymous'` | Атрибут script: `'anonymous'`/`'use-credentials'`; обычно менять не нужно, GitHub-вход не заменяет |

`enabled` и `shareAcrossLocales` — boolean true/false, а `strict`, `reactionsEnabled` и `emitMetadata` — строки `'0'`/`'1'`. Не смешивайте типы из-за похожего вида.

## Если комментариев нет или связь неправильная

| Симптом | Порядок проверки |
| --- | --- |
| Совсем нет области статьи | Включены ли статьи и заполнены ли четыре поля; переключатель заметок на статьи не влияет |
| Включение заметок сразу даёт ошибку | Заполнены ли все поля репозитория/категории, а не только переключатель |
| Удалённая ошибка или бесконечная загрузка | Настоящие ID, публичность, Discussions, доступ приложения, соответствующая категория, сеть и блокировщики |
| Разные статьи показывают одно обсуждение | Глобальный term/number, правильность общего режима и фактическое совпадение Giscus |
| Переводы не объединены | shareAcrossLocales, одинаковые slug и все ограничения общего mapping |
| После смены mapping комментарии «исчезли» | Проверьте старое обсуждение в GitHub; не меняйте многократно заголовки/ID и не удаляйте обсуждения для восстановления |
| Интерфейс всегда английский | Стандартный lang en; для страницы задайте `''`. Комментарии посетителей это не переводит |
| Локально изменилось, онлайн нет | Повторные сборка/размещение, не используется ли старая конфигурация |

Статьи отключаются через `theme.comments.enabled: false`, заметки — через `theme.fragments.comments.enabled: false`. Это убирает соответствующий вход/встраивание, не удаляя GitHub Discussions. Обновление темы не мигрирует обсуждения: сохраните mapping до обновления и проверьте связи после. Инструкция — в [руководстве установки](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/).

## Навигация по руководствам и настройкам

[Назад: настройка страниц и функций](https://demo.anglefeint.com/ru/blog/starter-guide-3-comments-about-and-theme-toggles/) · [Далее: другие языки](https://demo.anglefeint.com/ru/blog/starter-guide-languages/) · [Все восемь руководств](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/#tutorial-order).

Связанные настройки: [Giscus и общие обсуждения](https://demo.anglefeint.com/ru/blog/config-comments/), [переключатель комментариев заметок](https://demo.anglefeint.com/ru/blog/config-fragments/). Полные пути, значения и ограничения — в [общем справочнике](https://demo.anglefeint.com/ru/blog/config-reference/).
