For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ru/docs/web/troubleshooting.md (or send Accept: text/markdown).
Устранение неполадок
Диагностируйте проблемы установки на границе, которая действительно упала.
Настройка и конфигурация
Перед любым действием прочтите Перед началом работы и Основные сведения о терминале. В этих инструкциях предполагается, что вы открыли полный монорепозиторий 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. Если та же ошибка остается, включите команду и исправьте первую строку ошибки при обращении за помощью; никогда не отключайте проверку доступа и не записывайте секреты в журналы.
Не решайте падающую проверку отключением авторизации, логированием секретов или считанием пропущенных инфраструктурных проверок пройденными. Зафиксируйте маленькое воспроизведение и относящуюся не секретную конфигурацию. Перезапустите упавшую проверку после исправления, затем затронутые регрессионные тесты.