Build Komutunuz ve Çıkış Dizininizi Yapılandırma

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 projenizi doğru şekilde derlemek, Ayarlar'daki bir avuç alana bağlıdır: yükleme komutu, derleme komutu, çıktı dizini, kök dizini ve Node.js sürümü. Boş bırakıldığında otomatik olarak algılanırlar ve ilk dağıtım sorunlarının çoğu, çerçevenizin gerçekte yazdığı şeyle eşleşmeyen otomatik algılanan bir değerden kaynaklanır.

Ayarlar Nerede Bulunur

Projenizi Orbit'te açın, Ayarlar sekmesine gidin ve Derleme ayarları kartını bulun.

Alan	Ne yapar	Boş bırakıldığında yer tutucu
Yükleme komutu	Derleme öncesinde bağımlılıklar nasıl yüklenir	`npm ci (auto-detected)`
Derleme komutu	Çıktınızı üreten komut	`npm run build (auto-detected)`
Çıktı dizini	Derleme sonrasında Orbit'in yayınladığı klasör	`dist (auto-detected)`
Kök dizini	Monorepo'lar için uygulamanızı içeren alt dizin	`/ (monorepo subdirectory)`
Node.js sürümü	Derleme ve çalıştırma için kullanılacak ana Node sürümü	Platform varsayılanı

Herhangi bir alanı boş bırakarak Orbit'in otomatik olarak algılamasını sağlayın. Uygulamak için Derleme ayarları kartında Kaydet'e tıklayın.

Orbit proje ayarlarındaki derleme ayarları kartı

Derleme ayarını değiştirmek, şu anda yayında olan dağıtımı değiştirmez. Yeni ayar sonraki dağıtımdan itibaren geçerli olur. Kaydettikten sonra yeniden dağıtın, aksi takdirde hiçbir şey değiştiğini görmeyeceksiniz.

Çerçeve Varsayılanları

Next.js

Next.js'nin Orbit'te iki modu vardır ve yanlış olanı seçmek en yaygın ilk dağıtım hatasıdır.

Statik dışa aktarma (output: 'export' in next.config.js):

Derleme komutu: npm run build
Çıktı dizini: out
Sunucu modu: kapalı

Sunucu modu (SSR veya ISR), çoğu Next.js uygulaması için:

Ayarlar'da Runtime altında Sunucu modu'nu açın
Derleme komutu: npm run build
Çıktı dizini: .next

Sunucu modu etkinleştirilmeden, sunucu tarafından işlenen bir Next.js uygulaması statik dosyalar olarak yayınlanır. Ana sayfa genellikle yüklenecek ve her dinamik rota 404 verecektir. Bu sizin belirtinizse, bu sizin nedeninizdir: sunucu modunu açın ve başka bir şey değiştirmeden önce yeniden dağıtın.

Astro

Astro'nun çıktı klasörü her modda dist'dir. Değişen şey, sunucu moduna ihtiyacınız olup olmadığıdır.

output: 'static', varsayılan: çıktı dizini dist, sunucu modu kapalı
output: 'server' veya output: 'hybrid': çıktı dizini dist, sunucu modu açık
Derleme komutu: npm run build veya astro build

Vite (React, Vue, Svelte)

Derleme komutu: npm run build veya vite build
Çıktı dizini: dist

Vite, build.outDir'ı vite.config.ts'de geçersiz kılmadığınız sürece her zaman dist'e yazar. Geçersiz kıldıysanız, çıktı dizinini eşleşecek şekilde ayarlayın.

SvelteKit

Derleme komutu: npm run build
Çıktı dizini: build

Sunucu moduna ihtiyacınız olup olmadığı adaptörünüze bağlıdır: statik bir adaptör ihtiyaç duymaz, bir Node adaptörü yapar.

Nuxt 3

Derleme komutu: npm run build
Çıktı dizini: .output
Sunucu modu: açık

Remix

Derleme komutu: npm run build
Çıktı dizini: build
Sunucu modu: açık

Express veya Düz Node API

Derleme komutu: npm run build
Çıktı dizini: dist
Sunucu modu: açık

Sunucu modu derleme sonrasında npm start çalıştırır, bu nedenle start betiğinizin var olduğundan ve sunucuyu başlattığından emin olun.

Create React App

Create React App yukarı akışta kullanım dışıdır ve yeni bir proje için iyi bir seçim değildir, ancak mevcut olanlar iyi şekilde derlenir.

Derleme komutu: npm run build
Çıktı dizini: build

Düz HTML veya Statik Site Üreticisi

Eğer package.json yoksa yükleme komutunu boş bırakın
Deposu olduğu gibi yayınlamak için derleme komutunu boş bırakın veya üretecinizin komutunu ayarlayın
Çıktı dizini: depo kökü için . veya üretecinizin yazdığı klasör

Node.js Sürümü

Yalnızca ana sürüm numarasını girin: 18, 20 veya 22. Alan ipucu bunu açıkça söyler. 20.11.0 veya v20 gibi başka herhangi bir şey, bu alanın beklediği şey değildir.

Sürüm derlemeye ve sunucu modu açıkken çalışma zamanına da uygulanır.

Varsayılana güvenmek yerine sürümü sabitleyin. Daha yeni bir Node gerektiren bir bağımlılık yükleme sırasında "yanlış Node sürümü" denen bir hatayla başarısız olur ve sabitleme bu başarısızlık sınıfını tamamen ortadan kaldırır.

Monorepo'lar

Kök dizini'ni uygulamanızın yoluna ayarlayın, örneğin apps/web. Orbit, yükleme ve derleme komutlarınızı çalıştırmadan önce o dizine geçer ve çıktı dizini sonrasında ona bağlıdır.

Alan ipucu ikinci, daha yararlı davranışı anlatır: bu değişikliği yalnızca o yolun dışındaki dosyalar otomatik olarak atlanır. Dört Orbit projesine sahip bir monorepo, yalnızca bir işlemenin gerçekten dokunduğu uygulamaları yeniden derler, bu da hem zamanı hem de derleme dakikalarını tasarrufu sağlar.

Her ortam, Ayarlar'daki Hazırlama: derleme geçersiz kılmaları altında kök dizini bağımsız olarak geçersiz kılabilir, bu da hazırlama farklı bir çalışma alanını derlerken yararlıdır.

Hazırlama Geçersiz Kılmaları

Projenizin bir hazırlama ortamı varsa, Ayarlar aynı alanlarla bir Hazırlama: derleme geçersiz kılmaları bölümü gösterir. Orada boş bırakılan herhangi bir alan proje düzeyindeki değeri devralır, bu nedenle örneğin yalnızca hazırlama için derleme komutunu npm run build:staging'e değiştirebilir ve her şeyi olduğu gibi bırakabilirsiniz.

Hazırlama'nın yakındaki ilgili ayarları vardır: bir dal, bir erişim şifresi, bir IP beyaz listesi, başarısızlıkta otomatik geri alma ve bir Üretim ortam değişkenlerini devral geçişi.

Derleme Önbelleği

Orbit, Liftoff ve Apex planlarında derlemeler arasında node_modules'i önbelleğe alır. Dağıtım detay sayfası Önbellek isabeti veya Soğuk derleme ile birlikte yükleme aşaması süresini gösterir, bu nedenle önbelleğin projenizde ne kadar değerli olduğunu görebilirsiniz.

Tam bir yeniden yüklemeyi zorlamak için Ayarlar'ı açın, Derleme önbelleğini temizle'ye tıklayın ve onaylayın.

Derleme önbelleğini temizlemek geri alınamaz ve her ortam için sonraki dağıtım sıfırdan tam bir yükleme çalıştırır. Büyük bir monorepo'da bu yavaş bir derleme olduğundan, bir refleks yerine kasıtlı olarak yapın.

Yaygın Tuzaklar

"Derleme başarılı oldu ancak site 404 gösteriyor." Çıktı dizini yanlış: Orbit, derleme çıktınız olmayan bir klasör yayınladı. Derlemelerinizin gerçekten ne tür bir klasör oluşturduğunu kontrol edin. Vite dist'e yazar, Next.js statik dışa aktarma out'e yazar, Next.js sunucu modu .next'yi kullanır, Create React App ve Remix build'e yazar, Nuxt .output'e yazar.

"404 yalnızca dinamik rotalarda, ana sayfa iyi." Sunucu modu, ihtiyacı olan bir uygulamada kapalı. Yukarıdaki Next.js bölümüne bakın.

"Modül bulunamadı" ilk dağıtımda. Ya yükleme adımı çalışmadı, ya da yerel olarak kullandığınızdan farklı bir paket yöneticisiyle çalıştı. Yükleme komutunu açıkça ayarlayın: npm ci, yarn install --frozen-lockfile veya pnpm install --frozen-lockfile. Ayrıca tam olarak bir kilitli dosya taahhüt ettiğinizi kontrol edin: eğer hem package-lock.json hem de yarn.lock depoda varsa, algılanan paket yöneticisi sizin beklediğiniz olmayabilir.

"Kilitli dosya güncel değil." npm ci ve dondurulmuş kilitli dosya eşdeğerleri, kilitli dosya package.json ile anlaşmaz olduğunda çalışmayı reddeder. Paket yöneticisini yerel olarak çalıştırın ve yeniden oluşturulan kilitli dosyayı işleyin. Bu en yaygın ilk dağıtım hatası ve yerel olarak asla yeniden üretilmez, bu tam olarak neden kafa karıştırıcı olduğudur.

"Monorepo'mda yalnızca bir uygulama dağıtılıyor." Bu, kök dizinin işini yapıyor. Her uygulamanın kendi kök dizini olan kendi Orbit projesi gerekir.

"Yanlış Node.js sürümü." Node.js sürümü alanını yalnızca ana sürüm numarasına ayarlayın.

Derleme belleği tükeniyor veya diski dolduruyor. Her ikisi de derleme makinesindeki plan limitlerini aşıyor: Launch 1 vCPU, 1 GB RAM ve 4 GB disk alır; Liftoff 2, 2 GB ve 8 GB alır; Apex 4, 4 GB ve 16 GB alır. NODE_OPTIONS=--max-old-space-size=2048'ı ortam değişkeni olarak eklemek yalnızca makinenin gerçek RAM'ına kadar yardımcı olur. Bkz. Orbit Plan Sınırları.

İlgili Okumalar

Orbit'te Desteklenen Çerçeveler ve Çalışma Zamanları
Başarısız Derlemeleri Sorun Giderme
Ortam Değişkenleri derleme zamanı yapılandırması için