Настройка команды сборки и выходного каталога

Getting Orbit to build your project correctly comes down to a handful of fields in Settings: install command, build command, output directory, root directory and Node.js version. Left blank they are…

Настройка команды сборки и директории вывода для Orbit

Правильная сборка проекта в Orbit зависит от нескольких полей в разделе Settings: команда установки, команда сборки, директория вывода, корневая директория и версия Node.js. Если оставить их пустыми, они определяются автоматически, и большинство проблем при первом развёртывании возникают из-за автоматически определённого значения, которое не совпадает с тем, что фактически пишет ваш фреймворк.

Где найти параметры

Откройте проект в Orbit, перейдите на вкладку Settings и найдите карточку Build settings.

Поле	Назначение	Заполнитель при пусте
Install command	Как зависимости устанавливаются перед сборкой	`npm ci (auto-detected)`
Build command	Команда, которая создаёт ваш вывод	`npm run build (auto-detected)`
Output directory	Папка, которую Orbit публикует после сборки	`dist (auto-detected)`
Root directory	Для монорепозиториев: поддиректория, содержащая ваше приложение	`/ (monorepo subdirectory)`
Node.js version	Основной номер версии Node для сборки и запуска	Platform default

Оставьте любое поле пустым, чтобы позволить Orbit определить его автоматически. Нажмите Save на карточке Build settings для применения.

Карточка Build settings в параметрах проекта Orbit

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

Параметры по умолчанию для фреймворков

Next.js

Next.js имеет два режима в Orbit, и выбор неправильного режима - наиболее частая ошибка при первом развёртывании.

Статический экспорт (output: 'export' в next.config.js):

Команда сборки: npm run build
Директория вывода: out
Режим сервера: выключен

Режим сервера (SSR или ISR), что характерно для большинства приложений Next.js:

Включите Server mode в Settings под Runtime
Команда сборки: npm run build
Директория вывода: .next

Без включённого режима сервера приложение Next.js, отображаемое на сервере, публикуется как статические файлы. Главная страница обычно загружается, а каждый динамический маршрут выдаёт 404. Если это ваш симптом, вот его причина: включите режим сервера и повторно разверните перед какими-либо другими изменениями.

Astro

Папка вывода Astro - это dist во всех режимах. То, что меняется - нужен ли вам режим сервера.

output: 'static', по умолчанию: директория вывода dist, режим сервера выключен
output: 'server' или output: 'hybrid': директория вывода dist, режим сервера включен
Команда сборки: npm run build, или astro build

Vite (React, Vue, Svelte)

Команда сборки: npm run build, или vite build
Директория вывода: dist

Vite всегда пишет в dist, если вы не переопределили build.outDir в vite.config.ts. Если переопределили, установите директорию вывода в соответствии с этим.

SvelteKit

Команда сборки: npm run build
Директория вывода: build

Нужен ли вам режим сервера, зависит от вашего адаптера: статический адаптер его не требует, адаптер Node требует.

Nuxt 3

Команда сборки: npm run build
Директория вывода: .output
Режим сервера: включен

Remix

Команда сборки: npm run build
Директория вывода: build
Режим сервера: включен

Express или простой API на Node

Команда сборки: npm run build
Директория вывода: dist
Режим сервера: включен

Режим сервера запускает npm start после сборки, поэтому убедитесь, что ваш скрипт start существует и запускает сервер.

Create React App

Create React App устарел в исходном репозитории и не рекомендуется для новых проектов, но существующие проекты собираются без проблем.

Команда сборки: npm run build
Директория вывода: build

Простой HTML или статический генератор сайтов

Оставьте команду установки пустой, если нет package.json
Оставьте команду сборки пустой, чтобы опубликовать репозиторий как есть, или установите команду вашего генератора
Директория вывода: . для корня репозитория, или любая папка, в которую пишет генератор

Версия Node.js

Введите только номер основной версии: 18, 20 или 22. Подсказка поля это явно указывает. Любое другое значение, например 20.11.0 или v20, не соответствует ожиданиям этого поля.

Версия применяется к сборке и, когда режим сервера включен, также к среде выполнения.

Зафиксируйте версию вместо использования значения по умолчанию. Зависимость, требующая более новую версию Node, может неудачно установиться с ошибкой, которая редко говорит "неправильная версия Node" буквально, и фиксирование версии полностью исключает этот класс сбоев.

Монорепозитории

Установите Root directory в путь вашего приложения, например apps/web. Orbit переходит в эту директорию перед запуском команд установки и сборки, и директория вывода затем относится к ней.

Подсказка поля объясняет второе, более полезное поведение: развёртывания, при которых только файлы вне этого пути автоматически пропускаются. Монорепозиторий с четырьмя проектами Orbit пересобирает только приложения, которые коммит фактически изменил, что экономит как время, так и минуты сборки.

Каждая среда может независимо переопределять корневую директорию в разделе Staging: build overrides параметров, что полезно, когда staging собирает другой workspace.

Переопределения для Staging

Если ваш проект имеет промежуточную среду, параметры показывают раздел Staging: build overrides с теми же полями. Любое поле, оставленное пустым, наследует значение уровня проекта, поэтому вы можете изменить, например, только команду сборки для staging на npm run build:staging и оставить всё остальное без изменений.

Staging имеет собственные связанные параметры поблизости: ветку, пароль доступа, список разрешённых IP, автоматический откат при ошибке и переключатель Inherit production env vars.

Кэш сборки

Orbit кэширует node_modules между сборками в планах Liftoff и Apex. Страница деталей развёртывания показывает Cache hit или Cold build вместе с продолжительностью фазы установки, чтобы вы могли увидеть, какую пользу кэш приносит вашему проекту.

Чтобы принудительно выполнить полную переустановку, откройте Settings, нажмите Clear build cache и подтвердите.

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

Распространённые подводные камни

"Сборка успешна, но сайт показывает 404." Директория вывода неправильна: Orbit опубликовал папку, которая не является вашим выводом сборки. Проверьте, какую папку создаёт ваша сборка. Vite пишет dist, статический экспорт Next.js пишет out, режим сервера Next.js использует .next, Create React App и Remix пишут build, Nuxt пишет .output.

"404 только на динамических маршрутах, главная страница работает." Режим сервера выключен на приложении, которому он нужен. См. раздел Next.js выше.

"Module not found" при первом развёртывании. Либо этап установки не запустился, либо он запустился с другим пакетным менеджером, чем вы используете локально. Установите команду установки явно: npm ci, yarn install --frozen-lockfile, или pnpm install --frozen-lockfile. Также проверьте, что вы закоммитили ровно один файл блокировки: если package-lock.json и yarn.lock находятся в репозитории, обнаруженный пакетный менеджер может быть не тем, который вы ожидаете.

"Lockfile out of date." npm ci и эквиваленты frozen-lockfile отказываются запускаться, когда файл блокировки не совпадает с package.json. Запустите установку вашего пакетного менеджера локально и закоммитьте пересозданный файл блокировки. Это наиболее частый сбой при первом развёртывании, и он никогда не воспроизводится локально, что именно делает его запутанным.

"Только одно приложение в моём монорепозитории развёртывается." Это корневая директория, выполняющая свою работу. Каждому приложению нужен собственный проект Orbit с собственной корневой директорией.

"Неправильная версия Node.js." Установите поле версии Node.js в номер основной версии только.

Сборка выходит за пределы памяти или заполняет диск. Оба являются ограничениями плана на машине сборки: Launch получает 1 vCPU, 1 GB RAM и 4 GB диска; Liftoff получает 2, 2 GB и 8 GB; Apex получает 4, 4 GB и 16 GB. Добавление NODE_OPTIONS=--max-old-space-size=2048 в качестве переменной окружения помогает только до фактического объёма RAM машины. См. Ограничения планов Orbit.

Дополнительное чтение

Поддерживаемые фреймворки и среды выполнения в Orbit
Устранение неполадок при неудачных сборках
Переменные окружения для конфигурации во время сборки