リダイレクトとリライトの設定

Orbitには、プロジェクトがリクエストされる前に実行される組み込みリダイレクトおよびリライトエンジンがあります。KPanelまたはリポジトリ内のファイルで設定できます。本ガイドでは、両方の設定方法、パターン構文とそのキャプチャ、ルールの順序、制限、および予期しない動作をカバーしています。

ルールを設定する場所

2つの場所があり、固定の順序で評価されます。

1. KPanelで設定。 Orbitでプロジェクトを開き、Settingsに移動して、環境のredirects and rewritesセクションまでスクロールします。各環境には独立したルールセットがあるため、本番環境とステージング環境は別々に設定します。
2. リポジトリ内で、kaps.jsonファイルとして設定。 これについては後で説明します。

パネルルールが最初に評価されます。マッチするものがなければ、kaps.jsonルールが試されます。

KPanelでルールを追加する

1. Add ruleをクリック。
2. source（受信リクエストをマッチングするパスパターン）を入力。プレースホルダーは予想される2つの形式を示しています: /old-path or /blog/:slug。
3. destinationを入力。プレースホルダーは/new-path or https://...を示しているため、ローカルパスと完全な外部URLの両方が有効です。
4. ルールタイプを選択:
   • 301 Permanent: URLは恒久的に移動。ブラウザと検索エンジンはこれをキャッシュします。
   • 302 Temporary: 一時的に移動、キャッシュされない。キャンペーンと実験に使用。
   • Rewrite: ブラウザのアドレスバーのURLを変更せずに宛先パスを提供。
5. Save rulesをクリック。

ソースパスパターン

:idと:rest*の違いが重要です。名前付きパラメータは単一セグメントをマッチングし、次のスラッシュで停止します。スプラットは残りのすべてをマッチング（スラッシュを含む）。

宛先でキャプチャを使用する

名前付きパラメータを名前で参照し、ベアワイルドカードを*として参照:

ルールの順序

ルールはリストの上から下へテストされ、最初にマッチしたものが有効です。ルールがマッチングすると、それ以降のルールは考慮されません。パネルはリストの下に「ルールは順序でテストされます。最初にマッチしたものが有効です」と表示します。

ルールがマッチしない場合、リクエストは通常通り提供されます。

一般的な使用例

ページの名前変更

/about-usを/aboutに名前変更し、古いリンクが機能し続けるようにしたい。

• ソース: /about-us
• 宛先: /about
• タイプ: 301 Permanent

セクション全体の移動

ブログが/news/:slugから/blog/:slugに移動しました。

• ソース: /news/:slug
• 宛先: /blog/:slug
• タイプ: 301 Permanent

APIパスを無音でプロキシ

/api/v1/*を別の内部パスから提供し、変更を公開したくない。

• ソース: /api/v1/:path*
• 宛先: /api/internal/:path*
• タイプ: Rewrite

一時的なホールディングページ

• ソース: /checkout
• 宛先: /maintenance
• タイプ: 302 Temporary

トラフィックを別のドメインに送信

宛先は絶対URLである場合があるため、ルールは完全に異なるサイトを指すことができます。

• ソース: /shop/:rest*
• 宛先: https://shop.example.com/:rest*
• タイプ: 301 Permanent

kaps.jsonでのコード化による設定

ルールはパネルの代わりにリポジトリに配置できます。kaps.jsonファイルを追加し、ビルドがそれをoutput directoryにコピーすることを確認してください。Orbitはリポジトリルートではなく、ビルドされたアーティファクトのルートから読み取るためです。

{
  "redirects": [
    { "source": "/about-us", "destination": "/about", "permanent": true },
    { "source": "/news/:slug", "destination": "/blog/:slug", "permanent": true },
    { "source": "/promo", "destination": "/spring-sale", "permanent": false }
  ],
  "rewrites": [
    { "source": "/api/v1/:path*", "destination": "/api/internal/:path*" }
  ],
  "headers": [
    {
      "source": "/*",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}

permanent: trueは301を生成し、permanent: falseは302を生成します。省略すると301になります。

制限

• 環境ごとに最大100個のリダイレクトおよびリライトルール、およびkaps.json内に100個。
• 環境ごとに最大200個のカスタムヘッダールール。

制限を超えるルールはエラーが発生せずに無音でドロップされるため、制限をはるかに下回るようにしてください。

カスタムレスポンスヘッダー

リダイレクトとともに、各環境のSettings内にレスポンスヘッダーセクションがあり、マッチングパスにHTTPヘッダーを挿入します。これは同じパスパターン構文を使用し、HSTS、CSP、no-embed、no-sniff、referrer policy、CORSのクイック追加プリセットがあります。

リダイレクトとは異なり、すべてのマッチングヘッダールールが適用され、最初のものだけではなく、後のルールが同じヘッダーを設定する場合は前のものを上書きします。Content-Length、Transfer-Encoding、およびConnectionはブロックされています。それらを設定するとレスポンスが破損するためです。

それに依存する前に知る価値がある動作

• ルールはパスのみをマッチングします。 フラグメント（#section）はサーバーに届きません。ブラウザはリダイレクト後にそれらを再度アタッチします。
• 存在しないパスへのリライトは404を生成します。元のパスに無音で落ちるのではなく。リライトターゲットはビルド出力に存在する必要があります。
• ルールはプロジェクトがなにかリクエストされる前に実行されます。そのため、静的ファイルとサーバーモードリクエストの両方に適用されます。
• 各環境は独立しています。 本番環境のルールはステージング環境またはプレビューに適用されません。意図的にコピーしてください。

ルールを削除する

ルール行のゴミ箱アイコンをクリックし、Save rulesをクリックして変更を適用します。追加する場合と同様に、変更は次のデプロイメントから有効になります。

代わりにエッジ関数を使用する場合

リダイレクトエンジンはパス間ルールを処理します。ルールエンジンが表現できないロジックが必要な場合は、エッジ関数を使用してください: ヘッダーまたはクッキーへの分岐、クエリパラメータの保持または書き換え、重み付きA/Bルーティング、または条件付きのすべて。

関連する読み取り

• Edge Functions
• プロジェクトにカスタムドメインを追加
• プロジェクトをデプロイ