Weiterleitungen und Umschreibungen konfigurieren

Orbit hat ein integriertes Redirect- und Rewrite-System, das vor jeder Anfrage an Ihr Projekt ausgeführt wird. Es kann entweder in KPanel oder als Datei in Ihrem Repository konfiguriert werden. Dieser Leitfaden behandelt beide Methoden, die Mustersyntax und ihre Erfassungen, wie Regeln geordnet werden, die Limits und das Verhalten, das Menschen häufig überrascht.

Wo Sie Regeln Konfigurieren

Es gibt zwei Orte, und sie werden in einer festen Reihenfolge ausgewertet.

1. In KPanel. Öffnen Sie Ihr Projekt in Orbit, gehen Sie zu Settings, und scrollen Sie zum Abschnitt redirects and rewrites für die Umgebung. Jede Umgebung hat ihren eigenen unabhängigen Satz von Regeln, daher werden Production und Staging separat konfiguriert.
2. In Ihrem Repository, als kaps.json-Datei. Dies wird weiter unten behandelt.

Panel-Regeln werden zuerst ausgewertet. Wenn keine von ihnen passt, werden die kaps.json-Regeln versucht.

Hinzufügen einer Regel in KPanel

1. Klicken Sie auf Add rule.
2. Füllen Sie die source aus, das Pfadmuster für eingehende Anfragen. Der Platzhalter zeigt die zwei Formen, die er erwartet: /old-path or /blog/:slug.
3. Füllen Sie das destination aus. Der Platzhalter zeigt /new-path or https://..., sodass sowohl ein lokaler Pfad als auch eine vollständige externe URL gültig sind.
4. Wählen Sie den Regeltyp:
   • 301 Permanent: Die URL hat sich dauerhaft geändert. Browser und Suchmaschinen speichern dies.
   • 302 Temporary: Vorübergehend verschoben, nicht gecacht. Verwenden Sie für Kampagnen und Experimente.
   • Rewrite: Bedienen Sie den Zielpfad, ohne die URL in der Adressleiste des Browsers zu ändern.
5. Klicken Sie auf Save rules.

Quellpfad-Muster

Der Unterschied zwischen :id und :rest* ist der wichtige. Ein benannter Parameter passt auf ein einzelnes Segment und stoppt beim nächsten Schrägstrich. Ein Splat passt auf alles Verbleibende, einschließlich Schrägstriche.

Verwenden von Erfassungen im Ziel

Referenzieren Sie einen benannten Parameter nach Name und einen bloßen Platzhalter als *:

Regelreihenfolge

Regeln werden von oben nach unten getestet und das erste Match gewinnt. Sobald eine Regel passt, wird keine spätere Regel berücksichtigt. Das Panel sagt es unter der Liste: "Rules are tested in order. First match wins."

Wenn keine Regel passt, wird die Anfrage normal bedient.

Häufige Anwendungsfälle

Umbenennung einer Seite

Sie haben /about-us in /about umbenannt und möchten, dass alte Links weiterhin funktionieren.

• Quelle: /about-us
• Ziel: /about
• Typ: 301 Permanent

Verschieben eines ganzen Abschnitts

Ihr Blog ist von /news/:slug zu /blog/:slug verschoben worden.

• Quelle: /news/:slug
• Ziel: /blog/:slug
• Typ: 301 Permanent

Stillen Proxy eines API-Pfads

Sie möchten /api/v1/* von einem anderen internen Pfad aus bedient haben, ohne die Änderung preiszugeben.

• Quelle: /api/v1/:path*
• Ziel: /api/internal/:path*
• Typ: Rewrite

Eine vorübergehende Platzhalterseite

• Quelle: /checkout
• Ziel: /maintenance
• Typ: 302 Temporary

Traffic an eine andere Domain senden

Das Ziel kann eine absolute URL sein, daher kann eine Regel auf eine ganz andere Website zeigen.

• Quelle: /shop/:rest*
• Ziel: https://shop.example.com/:rest*
• Typ: 301 Permanent

Konfiguration als Code mit kaps.json

Regeln können in Ihrem Repository statt im Panel leben. Fügen Sie eine kaps.json-Datei hinzu, und stellen Sie sicher, dass Ihr Build sie in Ihr output directory kopiert, da Orbit sie aus dem Root des gebauten Artefakts und nicht aus dem Repository-Root liest.

{
  "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 erzeugt eine 301 und permanent: false eine 302. Das Weglassen ergibt eine 301.

Limits

• Bis zu 100 Redirect- und Rewrite-Regeln pro Umgebung und 100 in einer kaps.json.
• Bis zu 200 benutzerdefinierte Header-Regeln pro Umgebung.

Regeln über dem Limit werden stillschweigend gelöscht, anstatt einen Fehler auszulösen, daher bleiben Sie deutlich darunter.

Benutzerdefinierte Antwortheader

Neben Redirects hat jede Umgebung einen Abschnitt für Antwortheader in Settings zum Injizieren von HTTP-Headern bei übereinstimmenden Pfaden. Er verwendet dieselbe Pfadmustersyntax, und es gibt Quick-Add-Presets für HSTS, CSP, no-embed, no-sniff, referrer policy und CORS.

Im Gegensatz zu Redirects werden alle übereinstimmenden Header-Regeln angewendet, nicht nur die erste, und eine spätere Regel überschreibt eine frühere, wenn sie denselben Header setzen. Content-Length, Transfer-Encoding und Connection sind blockiert, da das Setzen sie die Antwort beschädigen würde.

Verhalten, das es Wert ist, zu kennen, bevor Sie sich darauf verlassen

• Regeln passen nur auf den Pfad. Fragmente (#section) erreichen den Server nie; der Browser hängt sie nach einem Redirect wieder an.
• Ein Rewrite zu einem Pfad, der nicht existiert, erzeugt einen 404, anstatt stillschweigend zum ursprünglichen Pfad zurückzufallen. Rewrite-Ziele müssen in Ihrer Build-Ausgabe existieren.
• Regeln werden ausgeführt, bevor Ihr Projekt nach etwas gefragt wird, daher gelten sie für statische Dateien und für Server-Mode-Anfragen gleichermaßen.
• Jede Umgebung ist unabhängig. Regeln in der Production gelten nicht für Staging oder Vorschau. Kopieren Sie sie bewusst.

Löschen einer Regel

Klicken Sie auf das Mülleimer-Symbol in der Regelzeile, und klicken Sie dann auf Save rules, um die Änderung anzuwenden. Wie beim Hinzufügen tritt die Änderung ab der nächsten Bereitstellung in Kraft.

Wann Sie stattdessen eine Edge Function verwenden

Das Redirect-System bearbeitet Pfad-zu-Pfad-Regeln. Greifen Sie zu einer Edge Function, wenn Sie Logik benötigen, die das Regel-System nicht ausdrücken kann: Verzweigung basierend auf einem Header oder Cookie, Beibehaltung oder Umschreiben von Abfrageparametern, gewichtetes A/B-Routing oder alles Bedingte.

Weiterführende Lektüre

• Edge Functions
• Hinzufügen einer benutzerdefinierten Domain zu Ihrem Projekt
• Bereitstellung Ihres Projekts