Orbit
Frameworks e Runtimes Suportados em Orbit
Orbit builds any project that installs with npm, yarn or pnpm and produces a folder of files or a Node.js server, and it detects the framework and package manager for you so most projects deploy…
O Que o Orbit Deteta Automaticamente
Quando uma compilação é executada, o Orbit regista o que encontrou e mostra-o para si:
- Framework, na página de detalhes de implementação e como um crachá nos cartões de implementação na visão geral do projeto.
- Gestor de pacotes, escolhido a partir do seu ficheiro de bloqueio:
package-lock.jsonfornece npm,yarn.lockfornece yarn,pnpm-lock.yamlfornece pnpm.
As definições de compilação em Settings são todas opcionais. Deixe um campo em branco e o seu marcador de posição diz-lhe o que será utilizado: Install command mostra npm ci (auto-detected), Build command mostra npm run build (auto-detected), e Output directory mostra dist (auto-detected).
Confirme exactamente um ficheiro de bloqueio. Se tanto package-lock.json como yarn.lock estão no repositório, o gestor de pacotes que o Orbit escolhe pode não ser o que utiliza localmente, e obtém uma instalação que se comporta de forma diferente da sua máquina sem motivo aparente. Elimine o que não está a utilizar.
Definições Por Framework
Estes são os valores que cada framework necessita. Onde o Orbit fornece um modelo inicial para o framework, o modelo utiliza exactamente estas definições.
| Framework | Build command | Output directory | Server mode |
|---|---|---|---|
| Next.js, static export | npm run build | out | Off |
| Next.js, SSR ou ISR | npm run build | .next | On |
| Astro, static | astro build | dist | Off |
| Astro, server ou hybrid | astro build | dist | On |
| Vite (React, Vue, Svelte) | npm run build | dist | Off |
| SvelteKit | npm run build | build | Depends on adapter |
| Nuxt 3 | npm run build | .output | On |
| Remix | npm run build | build | On |
| Express ou uma API Node simples | npm run build | dist | On |
| Create React App | npm run build | build | Off |
| HTML simples ou um gerador estático | deixe em branco, ou o comando do seu gerador | . ou a pasta em que escreve | Off |
Vite escreve sempre para dist a menos que tenha definido build.outDir em vite.config.ts. A pasta de saída do Astro é dist em todos os modos; o que muda entre modos é se precisa de modo servidor, não onde os ficheiros são colocados.
Modo Servidor
Server mode é uma opção de alternância em Settings, sob Runtime. Quando está ativado, o Orbit mantém a máquina de compilação viva executando npm start após cada implementação em vez de servir uma pasta de ficheiros estáticos.
Ative-o para Next.js com SSR, Remix, Nuxt, uma API Express e qualquer outra coisa que não seja uma exportação estática. Deixe-o desativado para uma compilação genuinamente estática.
Aplica-se a partir da próxima implementação, não à implementação que está actualmente ativa.
O sintoma clássico de um modo servidor em falta é um sítio onde a página inicial carrega perfeitamente e cada rota dinâmica devolve um 404. A compilação foi bem-sucedida, os ficheiros foram publicados, e simplesmente não há nenhum servidor a correr para responder às rotas. Se é isso que está a ver, ative o modo servidor e reimplemente antes de alterar mais nada.
Versão Node.js
Defina Node.js version em Settings sob Build settings. Introduza apenas o número da versão principal: 18, 20 ou 22. Deixe-o em branco para utilizar a predefinição da plataforma.
A versão aplica-se tanto à compilação como, quando o modo servidor está ativado, ao tempo de execução.
Fixe a versão explicitamente em vez de confiar na predefinição. Uma dependência que requer um Node mais recente do que a predefinição falha a instalação com um erro que não diz obviamente isso, e a fixação remove uma classe inteira de falhas de compilação "funcionou ontem".
Monorepos
Defina Root directory para o subdiretório que contém a aplicação, por exemplo apps/web. O Orbit muda para esse diretório antes de executar os seus comandos de instalação e compilação.
Também faz algo que deseja mas pode não esperar: pushes que apenas alteram ficheiros fora desse caminho são ignorados automaticamente. Um monorepo com quatro projetos Orbit portanto recompila apenas as aplicações que um commit realmente tocou.
Cada ambiente pode anular o diretório raiz separadamente, sob Staging: build overrides em Settings, o que é útil quando a preparação compila um espaço de trabalho diferente.
Definições de Compilação Personalizadas
Anule qualquer coisa em Settings, sob Build settings:
| Campo | Exemplo | Notas |
|---|---|---|
| Install command | npm ci | Ou yarn install --frozen-lockfile, pnpm install --frozen-lockfile |
| Build command | npm run build:prod | Executar exactamente conforme escrito |
| Output directory | dist/client | A pasta publicada após a compilação |
| Root directory | apps/frontend | Subdiretório de monorepo |
| Node.js version | 20 | Apenas versão principal |
Em branco significa detecção automática. Clique em Save no cartão de definições de compilação para aplicar.
A preparação pode anular qualquer uma destas independentemente, na secção Staging: build overrides. Um campo deixado em branco aí herda o valor ao nível do projeto, para que possa alterar apenas o comando de compilação para preparação e deixar tudo o resto igual.
Cache de Compilação
O Orbit coloca em cache node_modules entre compilações nos planos Liftoff e Apex. Quando a cache é utilizada, a implementação mostra um crachá Cache hit e a fase de instalação é muito mais curta. Uma compilação sem ela mostra Cold build.
Para forçar uma reinstalação completa, abra Settings, depois Clear build cache, e confirme. A próxima implementação para cada ambiente executa uma instalação completa do zero. Isto não pode ser desfeito, e a compilação após isso será lenta.
Recursos da Máquina de Compilação
O tamanho da máquina de compilação depende do seu plano, o que importa para grandes compilações:
| Plano | vCPU | RAM | Disco | Limite de tempo |
|---|---|---|---|---|
| Launch | 1 | 1 GB | 4 GB | 30 minutos |
| Liftoff | 2 | 2 GB | 8 GB | 30 minutos |
| Apex | 4 | 4 GB | 16 GB | 30 minutos |
Uma compilação que fica sem memória ou enche o disco falha com essa categoria de falha nomeada na página de implementação. Aumentar NODE_OPTIONS=--max-old-space-size ajuda apenas até à RAM real da máquina.
Começar a Partir de um Modelo
Se deseja uma implementação funcional antes de ter um repositório, utilize um modelo inicial. Em New project, mude de Import Git Repo para Start from Template e escolha um: Next.js com shadcn/ui, um sítio de marketing Astro, o Remix Indie Stack, um iniciador SvelteKit, uma aplicação Nuxt 3 mínima, ou uma API REST Express. O Orbit copia o modelo, aplica as definições de compilação corretas, e implementa-o.
Leitura Relacionada
- Configurar O Seu Comando De Compilação E Directório De Saída para o detalhe por framework e os erros habituais
- Resolução De Problemas De Compilações Falhadas
- Limites Do Plano Orbit