Configurar o Seu Comando de Compilação e Diretório de Saída

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…

Configurar o seu Projeto para Compilar Corretamente depende de um punhado de campos em Settings: comando de instalação, comando de compilação, diretório de saída, diretório raiz e versão do Node.js. Deixados em branco são auto-detectados, e a maioria dos problemas de primeira implementação vêm de um valor auto-detectado que não corresponde ao que o seu framework realmente escreve.

Onde Encontrar as Definições

Abra o seu projeto em Orbit, vá para o separador Settings e encontre o cartão Build settings.

Campo	O que faz	Marcador de posição quando em branco
Install command	Como as dependências são instaladas antes da compilação	`npm ci (auto-detected)`
Build command	O comando que produz o seu resultado	`npm run build (auto-detected)`
Output directory	A pasta que o Orbit publica após a compilação	`dist (auto-detected)`
Root directory	Para monorepos, o subdiretório que contém a sua aplicação	`/ (monorepo subdirectory)`
Node.js version	A versão principal do Node a utilizar para compilar e executar	Predefinição da plataforma

Deixe qualquer campo em branco para permitir que o Orbit auto-detecte. Clique em Save no cartão Build settings para aplicar.

Cartão Build settings nas definições do projeto Orbit

Alterar uma definição de compilação não altera a implementação que está atualmente em direto. A nova definição aplica-se a partir da próxima implementação. Reimplemente após guardar, ou nada parecerá ter acontecido.

Predefinições de Framework

Next.js

O Next.js tem dois modos em Orbit, e escolher o errado é o erro de primeira implementação mais comum.

Exportação estática (output: 'export' em next.config.js):

Comando de compilação: npm run build
Diretório de saída: out
Modo de servidor: desligado

Modo de servidor (SSR ou ISR), que é a maioria das aplicações Next.js:

Ative o Server mode em Settings, em Runtime
Comando de compilação: npm run build
Diretório de saída: .next

Sem o modo de servidor ativado, uma aplicação Next.js renderizada no servidor é publicada como ficheiros estáticos. A página inicial geralmente carregará e todas as rotas dinâmicas resultarão em 404. Se esse é o seu sintoma, esta é a sua causa: ative o modo de servidor e reimplemente antes de alterar qualquer outra coisa.

Astro

A pasta de saída do Astro é dist em todos os modos. O que muda é se precisa ou não do modo de servidor.

output: 'static', a predefinição: diretório de saída dist, modo de servidor desligado
output: 'server' ou output: 'hybrid': diretório de saída dist, modo de servidor ligado
Comando de compilação: npm run build, ou astro build

Vite (React, Vue, Svelte)

Comando de compilação: npm run build, ou vite build
Diretório de saída: dist

O Vite escreve sempre para dist a menos que tenha substituído build.outDir em vite.config.ts. Se o fez, defina o diretório de saída para corresponder.

SvelteKit

Comando de compilação: npm run build
Diretório de saída: build

Se precisa do modo de servidor depende do seu adaptador: um adaptador estático não precisa, um adaptador Node precisa.

Nuxt 3

Comando de compilação: npm run build
Diretório de saída: .output
Modo de servidor: ligado

Remix

Comando de compilação: npm run build
Diretório de saída: build
Modo de servidor: ligado

Express ou uma API Node Simples

Comando de compilação: npm run build
Diretório de saída: dist
Modo de servidor: ligado

O modo de servidor executa npm start após a compilação, por isso certifique-se de que o seu script start existe e inicia o servidor.

Create React App

O Create React App está deprecado na origem e não é uma boa escolha para um novo projeto, mas os existentes compilam bem.

Comando de compilação: npm run build
Diretório de saída: build

HTML Simples ou um Gerador de Site Estático

Deixe o comando de instalação em branco se não houver package.json
Deixe o comando de compilação em branco para publicar o repositório tal como está, ou defina o comando do seu gerador
Diretório de saída: . para a raiz do repositório, ou a pasta que o gerador escreve

Versão do Node.js

Introduza apenas o número da versão principal: 18, 20 ou 22. A dica do campo diz explicitamente. Qualquer outra coisa, como 20.11.0 ou v20, não é o que este campo espera.

A versão aplica-se à compilação e, quando o modo de servidor está ativado, também ao runtime.

Fixe a versão em vez de depender da predefinição. Uma dependência que precisa de um Node mais recente falha durante a instalação com um erro que raramente diz "versão Node errada" de forma tão explícita, e fixar remove completamente essa classe de falha.

Monorepos

Defina Root directory para o caminho da sua aplicação, por exemplo apps/web. O Orbit entra nesse diretório antes de executar os seus comandos de instalação e compilação, e o diretório de saída é então relativo a ele.

A dica do campo detalha o segundo comportamento, mais útil: implementações que alteram apenas ficheiros fora desse caminho são ignorados automaticamente. Um monorepo com quatro projetos Orbit recompila apenas as aplicações que um commit realmente tocou, o que economiza tempo e minutos de compilação.

Cada ambiente pode substituir o diretório raiz independentemente, em Staging: build overrides em Settings, o que é útil quando a preparação compila um espaço de trabalho diferente.

Substituições de Preparação

Se o seu projeto tem um ambiente de preparação, Settings mostra uma secção Staging: build overrides com os mesmos campos. Qualquer campo deixado em branco lá herda o valor ao nível do projeto, para que possa alterar apenas o comando de compilação para preparação, por exemplo para npm run build:staging, e deixar tudo o resto em paz.

A preparação tem as suas próprias definições relacionadas próximas: um ramo, uma senha de acesso, uma lista de permitidos de IP, reversão automática em caso de falha e um toggle Inherit production env vars.

Cache de Compilação

O Orbit coloca em cache node_modules entre compilações nos planos Liftoff e Apex. A página de detalhe da implementação mostra Cache hit ou Cold build, juntamente com a duração da fase de instalação, para que possa ver o que o cache vale no seu projeto.

Para forçar uma reinstalação completa, abra Settings, clique em Clear build cache e confirme.

Limpar o cache de compilação não pode ser desfeito, e a próxima implementação para cada ambiente executa uma instalação completa do zero. Num monorepo grande isso é uma compilação lenta, por isso faça-o deliberadamente em vez de como um reflexo.

Armadilhas Comuns

"Compilação bem-sucedida mas o site mostra 404." O diretório de saída está errado: o Orbit publicou uma pasta que não é o seu resultado de compilação. Verifique qual pasta a sua compilação realmente cria. O Vite escreve dist, a exportação estática Next.js escreve out, o modo de servidor Next.js utiliza .next, Create React App e Remix escrevem build, Nuxt escreve .output.

"404 apenas em rotas dinâmicas, a página inicial está bem." O modo de servidor está desligado numa aplicação que o precisa. Veja a secção Next.js acima.

"Module not found" na primeira implementação. Ou a etapa de instalação não foi executada, ou foi executada com um gestor de pacotes diferente do que utiliza localmente. Defina o comando de instalação explicitamente: npm ci, yarn install --frozen-lockfile, ou pnpm install --frozen-lockfile. Também verifique se tem exatamente um ficheiro de bloqueio commitado: se ambos package-lock.json e yarn.lock estão no repositório, o gestor de pacotes detectado pode não ser o que espera.

"Lockfile out of date." npm ci e os equivalentes de lockfile congelado recusam-se a executar quando o ficheiro de bloqueio discorda com package.json. Execute o install do seu gestor de pacotes localmente e commit ao ficheiro de bloqueio regenerado. Esta é a falha mais comum de primeira implementação e nunca reproduz localmente, que é exatamente por que é confusa.

"Apenas uma aplicação no meu monorepo está a ser implementada." Esse é o diretório raiz fazendo o seu trabalho. Cada aplicação precisa do seu próprio projeto Orbit com o seu próprio diretório raiz.

"Versão Node.js errada." Defina o campo de versão Node.js apenas para o número da versão principal.

A compilação fica sem memória ou preenche o disco. Ambos são limites de plano na máquina de compilação: Launch obtém 1 vCPU, 1 GB RAM e 4 GB disco; Liftoff obtém 2, 2 GB e 8 GB; Apex obtém 4, 4 GB e 16 GB. Adicionar NODE_OPTIONS=--max-old-space-size=2048 como variável de ambiente ajuda apenas até à RAM real da máquina. Veja Limites do Plano Orbit.

Leitura Relacionada

Frameworks e Runtimes Suportados em Orbit
Resolução de Problemas de Compilações Falhadas
Variáveis de Ambiente para configuração em tempo de compilação