Устранение неполадок при ошибках сборки

When an Orbit build fails, the deployment detail page gives you the full log plus a categorised failure summary and a suggested fix. This guide walks through reading that page, the failures Orbit…

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

Чтение ошибки

Откройте ваш проект в Kapsule Orbit.
Откройте вкладку Развёртывания.
Нажмите на развёртывание со статусом Ошибка.
Сначала прочитайте резюме ошибки выше журнала, затем сам журнал.

Развёртывание с ошибкой, показывающее категоризированное резюме ошибки

Kapsule Orbit присваивает каждой ошибке категорию: Недостаточно памяти, Ошибка компиляции, Ошибка теста, Ошибка линтера, Ошибка установки, Ошибка сети, Превышение времени ожидания или Неизвестная ошибка. Категория подсказывает вам, на какую часть конвейера нужно посмотреть перед тем, как читать даже одну строку журнала.

Также есть кнопка Получить диагностику AI. Она читает последние 120 строк журнала вместе с обнаруженным фреймворком и категорией ошибки и возвращает объяснение на естественном языке.

Диагностика помечена как создано AI, проверьте перед использованием. Рассматривайте её как очень хороший указатель на нужную строку журнала, а не как авторитет по вашему кодовому базу. Прочитайте строку, на которую она указывает, перед тем как что-либо менять.

Если сборка никогда не начиналась и зависает со статусом В очереди, перейдите к разделу о сборках в очереди ниже.

Ошибки, которые Kapsule Orbit распознаёт по названиям

Они имеют конкретное предлагаемое исправление на странице развёртывания.

Что Kapsule Orbit обнаруживает	Что это означает	Исправление
Отсутствует модуль	Импорт указывает на пакет, который не установлен	Добавьте пакет в `package.json` и выполните коммит, или исправьте опечатку в пути импорта
`ERESOLVE` конфликт	npm не может удовлетворить зависимость peer dependency	Решите конфликт в `package.json`, или добавьте `--legacy-peer-deps` в вашу команду установки в Настройках
Ошибка TypeScript	Проверка типов не прошла во время сборки	Исправьте перечисленные ошибки. При проблемах с типами третьих сторон `skipLibCheck: true` в `tsconfig.json`
Недостаточно памяти	Сборка превысила оперативную память машины сборки	Добавьте `NODE_OPTIONS=--max-old-space-size=2048` как переменную окружения, или перейдите на план с более мощной машиной сборки
Диск сборки переполнен	Сборка заполнила диск целиком	Найдите неожиданно большой `node_modules` или артефакт, или перейдите на план с более крупным диском сборки
Сборка превысила время	Сборка достигла лимита в 30 минут	Включите кэш сборки, уменьшите размер бандла или найдите, что зависает
Пакет не найден (404)	Зависимость не существует с таким названием или версией	Проверьте `package.json` на опечатку или подтвердите, что пакет опубликован
Ошибки ESLint	Ошибки линтера заблокировали сборку	Исправьте их, или остановите линтер от блокирования сборки в конфигурации фреймворка
Синтаксическая ошибка	Исходный код не может быть распарсен	Отсутствует скобка, незакрытая строка, или синтаксис, не поддерживаемый вашей версией Node
Файл не найден	Упоминаемый файл отсутствует в репозитории	Подтвердите, что он закоммичен, и проверьте регистр пути
Lockfile устарел	Lockfile не совпадает с `package.json`	Запустите установку вашего менеджера пакетов локально и выполните коммит обновлённого lockfile

Несовпадение lockfile это самая распространённая ошибка при первом развёртывании, и самая запутанная, потому что она никогда не происходит локально. npm ci, yarn install --frozen-lockfile и pnpm install --frozen-lockfile отказываются продолжать, когда lockfile расходится с package.json. Переустановите lockfile локально и выполните его коммит.

Распространённые ошибки по фазам

Установка зависимостей завершилась с ошибкой

Фаза Установка завершилась с ошибкой.

Неправильный менеджер пакетов. Kapsule Orbit выбирает npm, yarn или pnpm из вашего lockfile. Если закоммичено более одного lockfile, выбор может отличаться от ожидаемого. Удалите те, которые вы не используете, или явно установите Команду установки в Настройках.
Приватный реестр. Если зависимость исходит из приватного реестра, токен аутентификации должен быть доступен во время сборки как переменная окружения, и ваш .npmrc должен на него ссылаться.
Несовпадение версии Node.js. Некоторые пакеты требуют минимальную версию Node. Установите Версию Node.js в Настройках на номер основной версии: 18, 20 или 22.
Недостаточно памяти для большого монорепо. Используйте npm ci вместо npm install, и рассмотрите план с более мощной машиной сборки.

Команда сборки завершилась с ошибкой

Фаза Сборка завершилась с ошибкой.

Ошибки TypeScript или линтера. Kapsule Orbit запускает вашу команду сборки точно так, как она написана. Если сборка завершается локально с ошибкой, она завершится и здесь.
Отсутствует переменная окружения сборки. Переменная, читаемая во время сборки, должна существовать перед запуском сборки, а не только во время выполнения. Добавьте её на вкладку Переменные окружения и переразверните. Переменная окружения сборки, добавленная после развёртывания, не применяется к нему ретроспективно.
Неправильный корневой каталог в монорепо. Установите Корневой каталог в Настройках на путь приложения, например apps/web.

Сборка превышает время ожидания

Сборки прерываются через 30 минут по реальному времени на всех планах. Если ваша постоянно приближается к этому лимиту:

Проверьте логи на предмет процесса, ожидающего ввода. Сборка, которая требует ввода, зависает.
Избегайте --legacy-peer-deps на большом дереве зависимостей, если это вам не требуется.
Убедитесь, что используется кэш сборки. Планы Liftoff и Apex включают его; на странице развертывания показано Cache hit или Cold build.
Перейдите на план с большим количеством vCPU для сборки. Смотрите Ограничения планов Kapsule Orbit.

Сборка никогда не начинается

Развертывание, застрявшее на Queued, ожидает освобождения слота сборки. На странице деталей показана ваша позиция в очереди и количество используемых одновременных слотов сборки; сборка запускается автоматически, когда освобождается один из них. Launch и Liftoff позволяют одну одновременную сборку; Apex позволяет три.

Все процессы, выполняемые в вашей учетной записи, можно просмотреть в Kapsule Orbit, затем Queue.

Если развертывание остается в очереди и ничего больше не запущено, скорее всего оно задерживается, а не стоит в очереди. Проверьте:

Awaiting approval, если включено Require approval for production
deploy lock на проекте
deploy freeze schedule, блокирующий текущее время или день
CI required checks, ожидающие вашего pipeline
Require staging success before production, ожидающее развертывание staging с тем же коммитом

Сборка была полностью пропущена

Если push не создал развертывание вообще, это, вероятно, был фильтр намеренно:

Ignored paths: каждый файл в push совпадает с шаблоном вроде *.md или docs/**
Branch ignore patterns: ветка совпадает с чем-то вроде dependabot/*
Root directory: ничего в push не затронуло поддиректорию monorepo для этого проекта
Branch previews отключены, и push был не в production или staging

Сборка прошла успешно, но сайт работает неправильно

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

404 на каждой странице. Output directory неправильно: Kapsule Orbit опубликовал папку, которая не является вашим выходом сборки. Проверьте, что на самом деле пишет ваша сборка. Распространенные значения: dist, .next, out, build и .output.

404 только на динамических маршрутах. Приложение требует запущенного сервера, но предоставляется как статические файлы. Включите Server mode в Settings в разделе Runtime. Это необходимо для Next.js с SSR, Remix, Nuxt и всего, что не является статическим экспортом.

Assets 404 после развертывания для пользователей, которые уже находились на сайте. Они загрузили старую страницу и запрашивают старые URL-адреса bundle, которые больше не существуют. Включите Skew protection в Settings, что сохраняет артефакты предыдущей сборки доступными в течение периода хранения после развертывания новой версии.

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

Параметры сборки для конкретной платформы находятся в Настройке команды сборки и выходного каталога.

Повторные попытки

На странице неудачного развертывания:

Retry build повторно запускает тот же коммит.
More retry options, затем Retry with cleared cache, удаляет кэш сборки сначала.

Вы также можете указать Kapsule Orbit повторить попытку за вас. Build auto-retry в Settings повторно ставит в очередь неудачные сборки, вызванные ошибками инфраструктуры, такими как сбой сети или истечение времени ожидания, до трех раз. Намеренно не повторяет ошибки кода, поэтому ошибка компиляции, lint или test никогда не зацикливается.

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

Остановка неудачной сборки перед попаданием к пользователям

Если развертывание уже вступило в силу и что-то сломало, выполните откат, а не пытайтесь исправить в спешке. Откат продвигает уже построенный артефакт и занимает секунды. Смотрите Откат развертывания.

Чтобы остановить дальнейшие развертывания во время расследования, нажмите Lock deploys на проекте. Развертывания, инициированные push, затем пропускаются до разблокировки, в то время как ручные развертывания по-прежнему работают, чтобы вы могли отправить исправление.

Вы также можете указать Kapsule Orbit делать это автоматически: Auto-rollback on failure восстанавливает последнее здоровое развертывание, если развертывание production терпит неудачу, и Health check path восстанавливает его, когда новое развертывание не отвечает кодом 2xx в течение 15 секунд.

Все еще застряли

Если лог просто заканчивается без сообщения об ошибке, процесс сборки, скорее всего, был завершен: нехватка памяти или машина сборки была освобождена. Попытайтесь еще раз. Если это повторится дважды таким же образом, откройте тикет из KPanel или отправьте письмо на support@kapsulehost.com и включите ID развертывания, показанный на странице деталей.