> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

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

Диагностируйте проблемы установки на границе, которая действительно упала.

## Настройка и конфигурация

Перед любым действием прочтите [Перед началом работы](https://supastack.dev/ru/docs/web/before-you-start.md) и [Основные сведения о терминале](https://supastack.dev/ru/docs/web/terminal-basics.md). В этих инструкциях предполагается, что вы открыли полный монорепозиторий supastack в VS Code; его корень package.json отмечает корень репозитория. В командах pnpm пакет рабочей области представляет собой папку приложения или общего кода; В продукте рабочее пространство — это контейнер данных и граница безопасности команды. corepack pnpm --filter ... выбирает один пакет из монорепозитория, пока команды выполняются из его корня. Если вы открыли только синхронизированную папку мобильного устройства или рабочего стола, она не содержит веб-серверной части, настройки Docker или корневых сценариев: запустите серверную часть из этого монорепозитория или доступного размещенного сервера и используйте собственные сценарии папки платформы. Переменная среды — это именованный параметр, хранящийся в локальном файле .env или на панели управления хостингом; перезапустите соответствующее приложение после его изменения и не допускайте попадания секретов сервера в значения NEXT_PUBLIC_ и EXPO_PUBLIC_.

1. Скопируйте первую полезную строку ошибки и команду, вызвавшую ее; не вставляйте секретные значения.

2. Из корня репозитория запустите corepack pnpm --filter @supastack/web typecheck для ошибок веб-типа или corepack pnpm test для автоматизированного пакета.

3. В случае проблемы с браузером запустите Интернет с помощью corepack pnpm --filter @supastack/web dev и воспроизведите его по адресу http://localhost:3000.. Ожидается: перед изменением настроек вы можете определить, связана ли ошибка с установкой, кодом, базой данных, поставщиком или браузером.

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

```
corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm test
```


## Команды для копирования

Следуйте комментариям, чтобы узнать, в какой папке запускается команда. Если помечены два терминала, откройте два окна терминала и продолжайте выполнять первую команду, пока используете вторую.

```
corepack pnpm --filter @supastack/web typecheck
corepack pnpm test
```


## Ошибки первого запуска — расшифровка

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

| Симптом | Вероятная причина | Первое исправление |
|---|---|---|
| node, corepack или pnpm не распознаётся / command not found | Инструмент не установлен, или терминал был открыт до завершения установки | Установите его (или переоткройте терминал), затем повторите node --version |
| package.json не найден / ENOENT package.json | Терминал находится не в той папке | Выполните cd в корень репозитория — папку, содержащую package.json — и повторите |
| EADDRINUSE / порт 3000 уже используется | Другой dev-сервер всё ещё занимает порт | Найдите терминал того сервера и нажмите Ctrl + C, затем запустите снова |
| ECONNREFUSED к localhost:5432 или ошибка подключения к базе данных | Postgres не запущен | Выполните docker compose up -d postgres, дождитесь статуса healthy, затем повторите |
| Ошибка валидации env, называющая отсутствующий ключ | apps/web/.env.local отсутствует или содержит пустое обязательное значение | Скопируйте названный ключ из .env.example, задайте ему значение, сохраните и перезапустите сервер |
| corepack или pnpm отсутствует после corepack enable | В PATH нет shim pnpm | Используйте corepack pnpm ... напрямую — ему никогда не нужен shim; в Windows используйте corepack.cmd |
| PowerShell сообщает, что скрипт .ps1 не может быть запущен / заблокирован | Политика скриптов PowerShell блокирует shim | Используйте форму .cmd — corepack.cmd pnpm install — изменение политики не требуется |


## Рабочий процесс внедрения

При отсутствии доступа к API проверьте, что сервер запущен и настроенный origin совпадает с клиентом. При недоступных выборах AI инспектируйте AI_MODEL_POLICY и включённые строки каталога. При неопределённой задаче в очереди используйте сохранённый поток восстановления вместо новой отправки.

При проблемах макета в браузере инспектируйте вычисленные стили и воспроизводите точный вьюпорт. Токены продуктового chrome живут в app-theme.css (пакеты из catalog.ts); блокировка маркетингового бренда — в theme.css. Переопределения компонентов всё равно могут побеждать через специфичность. Проверяйте отрисованный радиус, а не только объявление токена.


## Проверка и устранение неполадок

Если страница находится на :3001, откройте :3000 для веб-приложения; :3001 принадлежит отдельному серверу apps/docs. Если тест запрашивает доступ к базе данных, используйте изолированную базу данных разработки и проверьте оба местоположения .env. Если та же ошибка остается, включите команду и исправьте первую строку ошибки при обращении за помощью; никогда не отключайте проверку доступа и не записывайте секреты в журналы.

Не решайте падающую проверку отключением авторизации, логированием секретов или считанием пропущенных инфраструктурных проверок пройденными. Зафиксируйте маленькое воспроизведение и относящуюся не секретную конфигурацию. Перезапустите упавшую проверку после исправления, затем затронутые регрессионные тесты.


## Вперёд

[Как пользоваться этой документацией](https://supastack.dev/ru/docs/web/using-the-docs.md)