Orbit
環境変数
Environment variables hold the configuration and secrets your app needs at build time and at runtime, such as API keys, database URLs and feature flags, without any of it living in your repository…
環境変数はビルド時とランタイムにアプリが必要とする設定とシークレットを保持します。例えば API キー、データベース URL、フィーチャーフラグなど、リポジトリに含まれることはありません。このガイドでは、Orbit での環境変数の場所、スコープと優先順位の仕組み、値をシークレットにマークする方法、一括インポートとエクスポート、および変数が常に未定義になる原因となる間違いについて説明します。
環境変数の場所
Orbit でプロジェクトを開き、/orbit/<project-id>/env-vars の Env vars タブをクリックします。
このページはセクションに分かれています:
- All environments (最上部): プロジェクト全体の変数で、すべてのビルドで利用できます。
- 環境ごとの折りたたみセクション (Production、Staging、その他のプレビュー): その環境のオーバーライドを保持します。
リストの上には検索ボックスと Secrets only フィルタがあり、長いリストを素早く操作できます。
スコープの仕組み
| スコープ | 影響範囲 |
|---|---|
| All environments (プロジェクト全体) | このプロジェクトのすべてのビルドに挿入されます |
| Environment-level override (環境レベルのオーバーライド) | その環境のみに適用され、同じキーのプロジェクト全体の値より優先されます |
ページのサブタイトルにはルールが明記されています: プロジェクト全体の変数はすべてのビルドで利用でき、環境レベルのオーバーライドが優先されます。
典型的なセットアップは、テストデータベースを指すプロジェクト全体の DATABASE_URL で、本番レベルのオーバーライドが実際のデータベースを指すようにしたものです。本番ビルドは実際のデータベースを取得し、その他すべてはテストデータベースを取得し、後で追加するものは誤って本番認証情報をプレビューに漏らしません。
また、プロジェクト全体の変数には Available in コントロールがあり、特定の環境タイプ (production、staging、preview) をその他の場合はプロジェクト全体である変数から除外できます。
環境ごとのスコープの詳細 (セキュリティの理由を含む) については、環境ごとの環境変数の設定 を参照してください。
プロジェクト全体の変数はブランチプレビュービルドに挿入され、プレビュー URL はリンクを持つ誰でも公開でアクセスできます。本番データベースの認証情報、ライブ支払いキー、管理者トークンは本番のみにスコープする必要があります。これはこのページで最も重要なことです。
変数を追加する
- Env vars タブの下部にある Add variable フォームまでスクロールします。
- KEY を入力します。例:
NEXT_PUBLIC_API_URL - value を入力します。
- Scope を選択します: All environments (project-wide) または特定の環境のオーバーライド。
- プロジェクト全体を選択した場合、Available in ボタンを使用して、この変数が到達しないすべての環境タイプを選択解除します。
- 機密情報の場合は Mark as secret にチェックを入れます。
- Add をクリックします。
フォームはコミットする前に実行内容を告げます: 環境オーバーライドはその環境のビルドのみに適用されることを示す通知を表示し、制限されたプロジェクト全体の変数は挿入される環境タイプを表示します。
変更が有効になるタイミング
変数を追加、編集、削除しても、現在ライブになっているデプロイメントは変わりません。変数はビルドが実行されるときに挿入されるため、変更は 次のデプロイメント から適用されます。アプリが依存しているものを変更した後は、再デプロイしてください。
Orbit はこれについて明示的です。デプロイメントの詳細ページを開き、ビルド後に設定が変更されている場合、Environment variables updated since this deployment という通知が表示されて、変更は再デプロイするまで有効にならないことが示されます。
シークレット
チャットに貼り付けないものはすべて Mark as secret にチェックを入れます: API キー、データベースパスワード、トークン、署名キー。
シークレット値はパネルでマスクされ、secret バッジが付きます。非シークレット値は (plain) マーカーを表示します。
シークレットの値は保存後は読み取ることができません。あなたもパネル内の他の誰も読み取ることができません。編集アイコンをクリックして新しい値を入力し、保存することで置き換えることはできますが、表示することはできません。ここに保存する前に、パスワードマネージャーに独自のコピーを保持してください。
Orbit は値がどのくらいの期間存在していたかも追跡し、古い変数にエイジバッジを表示し、ローテーションを示唆するヒントを表示します。これは強制ではなく、促す働きをします。
編集と削除
変数の横の編集アイコンをクリックして、その値を変更します。Delete をクリックして削除し、確認します: ダイアログは、それに依存するビルドが破損することを警告します。これは次のデプロイメント時に何が起こるかの正確な説明です。
一括インポートとエクスポート
タブの上部にある 2 つのボタンが一括作業を処理します。
Import .env はペーストボックスを開きます。.env ファイルの内容を貼り付けて、スコープを選択すると、Orbit は検出された変数の数と、シークレットとしてマークする数を知らせます。キー名に基づいて自動的にフラグを立てるため、SECRET、TOKEN、KEY、PASSWORD などを含むすべてはインポート前にシークレットとしてマークされます。Overwrite existing variables with the same key オプションがあり、デフォルトではオフです。
Download .env は変数 名前のみ を含むテンプレートを生成し、値は含みません。バックアップとして使用するのではなく、チームメイトが自分の値を入力できるように共有することを目的としています。
.env テンプレートをダウンロードすると、非シークレット変数を含む値は含まれません。Orbit から値をエクスポートする方法はありません。値のコピーが必要な場合は、元々生成された場所から取得してください。
環境間で変数をコピーする
Copy variables between environments パネルは 1 つのスコープから別のスコープに変数セット全体をコピーします。From (プロジェクトレベルまたは特定の環境) と To を選択し、必要に応じて Overwrite variables that already exist in the target にチェックを入れて、Preview をクリックすると、コミットする前に追加、更新、スキップされる正確な数が表示されます。
また、本番ステージングと環境を キー ごとに比較し、1 つのみ、異なる、一致するものを報告する Env sync check ページもあります。「ステージングは機能するが本番は機能しない理由」というツールに適しています。
プロジェクト間で変数を共有する
複数のプロジェクトが同じ認証情報を必要とする場合、各プロジェクトにコピーするのではなく、env group を使用します。Orbit に移動して Env groups をクリックし、グループを作成してそのグループに変数を追加し、それらを必要とするプロジェクトをリンクします。
グループ変数はビルド時に挿入され、プロジェクトレベルと環境レベルの変数がグループ変数より優先されます。アカウント上に最大 20 個のグループを持つことができます。
フレームワークのメモ
ブラウザに到達する変数は Orbit ではなくフレームワークによって決まります。Orbit はスコープ内のすべてを挿入し、フレームワークは何を公開するかを決定します。
- Next.js:
NEXT_PUBLIC_で始まるキーはビルド時にブラウザバンドルに挿入されます。その他はサーバー側のままです。 - Vite:
VITE_で始まるキーはブラウザに公開されます。その他はビルド時のみです。 - Node.js アプリ: スコープ内のすべてはビルド中に
process.envにあり、Server mode がオンの場合はランタイムにもあります。
値をシークレットとしてマークしてから NEXT_PUBLIC_ または VITE_ というプレフィックスを付けないでください。シークレットフラグは、パネルに値を表示するかどうかのみを制御し、プレフィックスはフレームワークがそれを訪問者のブラウザに送信するかどうかを制御します。プレフィックスが優先されます。
ビルドが実際に受け取ったものを確認する
すべてのデプロイメント詳細ページには、ビルド時に挿入された環境変数の キー がリストされており、現在の設定と比較します: 追加、変更、削除、変更なし。青緑色のキーは環境固有のオーバーライドから来たもので、灰色のものはプロジェクトレベルから来たものです。値は保存または表示されませんが、キーをホバーすると SHA-256 フィンガープリントが表示されます。これは値を表示しなくても 2 つの環境が同じ値を保持していることを確認するのに十分です。
これは「変数は実際にビルドに到達しているか」の最終的な答えです。その他の変更を行う前に確認してください。
トラブルシューティング
変数がランタイムで未定義です。 デプロイメントが変更をポストするかどうかを確認し、スコープがこの環境をカバーしているかどうかを確認し、上記のフレームワークプレフィックスルールを確認します。その順序で。
本番で機能していますがプレビューで機能していません。 変数は本番のみにスコープされているか、プロジェクト全体の変数の Available in の下で preview が選択解除されています。これは通常意図的です。
ローカルで機能していますがビルドで機能していません。 ローカルの .env ファイルはリポジトリに含まれていない、および含まれるべきではありません。Import .env でインポートして、適切なスコープを選択します。
Staging が本番にあるすべてのものを欠いています。 Settings の Staging: environment variables で Inherit production env vars をオンにするか、Copy variables between environments を使用します。