ビルドコマンドと出力ディレクトリの設定

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でプロジェクトを正しくビルドするには、Settingsの以下のフィールドが重要です: インストールコマンド、ビルドコマンド、出力ディレクトリ、ルートディレクトリ、Node.jsバージョン。これらを空白にしておくと自動検出されますが、ほとんどの初回デプロイの問題は、フレームワークが実際に出力するファイルと一致しない自動検出値に由来します。

設定を見つける場所

Orbitでプロジェクトを開き、Settingsタブに移動して、Build settingsカードを探します。

フィールド	機能	空白時のプレースホルダ
インストールコマンド	ビルド前に依存関係をインストールする方法	`npm ci (auto-detected)`
ビルドコマンド	出力を生成するコマンド	`npm run build (auto-detected)`
出力ディレクトリ	ビルド後にOrbitが公開するフォルダ	`dist (auto-detected)`
ルートディレクトリ	モノレポの場合、アプリを含むサブディレクトリ	`/ (monorepo subdirectory)`
Node.jsバージョン	ビルドと実行に使用するメジャーNodeバージョン	プラットフォームのデフォルト

フィールドを空白にしておくと、Orbitが自動検出します。Build settingsカードのSaveをクリックして適用します。

Orbitプロジェクト設定のBuild settingsカード

ビルド設定を変更しても、現在ライブなデプロイメントは変わりません。新しい設定は次のデプロイメントから適用されます。保存後に再デプロイするか、何も変わっていないように見えます。

フレームワークのデフォルト

Next.js

Next.jsはOrbitで2つのモードを持ち、間違ったものを選ぶことが最も一般的な初回デプロイの失敗です。

静的エクスポート (output: 'export' in next.config.js):

ビルドコマンド: npm run build
出力ディレクトリ: out
サーバーモード: オフ

サーバーモード (SSRまたはISR)、ほとんどのNext.jsアプリ:

SettingsのRuntimeでServer modeをオンにします
ビルドコマンド: 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またはプレーンNode API

ビルドコマンド: 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.jsが必要な依存関係は、インストール中に「間違ったNode.jsバージョン」とはっきり述べないエラーで失敗し、バージョンを固定することでこのクラスの失敗を完全に排除できます。

モノレポ

Root directoryをアプリのパスに設定します。例えばapps/web。Orbitはそのディレクトリに移動してからインストールおよびビルドコマンドを実行し、出力ディレクトリはその相対パスになります。

フィールドのヒントは、より有用な動作を説明しています: そのパスの外のファイル変更を自動的にスキップします。4つのOrbitプロジェクトを持つモノレポは、コミットが実際に触れたアプリのみを再ビルドするため、時間とビルド分数の両方を節約できます。

各環境は、Settings内のStaging: build overridesでルートディレクトリを独立してオーバーライドできます。これはステージングが異なるワークスペースをビルドするときに便利です。

ステージングのオーバーライド

プロジェクトにステージング環境がある場合、Settingsは同じフィールドを持つStaging: build overridesセクションを表示します。そこで空白にしたフィールドはプロジェクトレベルの値を継承するため、例えばステージング用のビルドコマンドをnpm run build:stagingに変更して、他はそのままにしておくことができます。

ステージングには近くに独自の関連設定があります: ブランチ、アクセスパスワード、IPアローリスト、失敗時の自動ロールバック、およびInherit production env varsトグル。

ビルドキャッシュ

OrbitはLiftoffおよびApexプランでビルド間でnode_modulesをキャッシュします。デプロイメント詳細ページには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。また、ロックファイルが正確に1つだけコミットされていることを確認してください: package-lock.jsonとyarn.lockがリポジトリ内にある場合、検出されたパッケージマネージャーは予想するものではない可能性があります。

「ロックファイルが古い状態です」。 npm ciおよびフローズンロックファイルの同等物は、ロックファイルがpackage.jsonと矛盾するときに実行を拒否します。ローカルでパッケージマネージャーをインストール実行し、再生成されたロックファイルをコミットします。これは最も一般的な初回デプロイの失敗で、ローカルでは決して再現しません。これがまさに混乱する理由です。

「モノレポの1つのアプリのみをデプロイしています。」 それはルートディレクトリがその仕事をしています。各アプリは独自のルートディレクトリを持つ独自の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プラン制限を参照してください。