Weiterleitungen – gooddeploy

Weiterleitungen eintragen

Leg im Projekt-Root eine gooddeploy.json an (oder ergänze sie) und committe sie:

{
  "$schema": "https://gooddeploy.de/schema/v1.json",
  "redirects": [
    { "source": "/blog/:slug", "destination": "/news/:slug" },
    { "source": "/impressum.html", "destination": "/impressum", "permanent": true },
    { "source": "/aktion", "destination": "/angebote", "permanent": false },
    { "source": "/docs/:path*", "destination": "https://docs.example.de/:path*", "statusCode": 301 }
  ]
}

git add gooddeploy.json
git commit -m "Weiterleitungen für alte Adressen"
gooddeploy deploy

Die Weiterleitungen gelten ab dem nächsten Deploy, in der Preview genauso wie nach promote live. Zurück geht es wie immer mit gooddeploy rollback.

Feld	Bedeutung
`source`	Pfad, der weitergeleitet wird, beginnt mit `/`, ohne Query (`?…`)
`destination`	neuer Pfad (`/neu`) oder volle Adresse (`https://…`), Platzhalter aus `source` erlaubt
`permanent`	`true` (Standard): dauerhaft, Status 308; `false`: vorübergehend, Status 307
`statusCode`	statt `permanent`: 301, 302, 303, 307 oder 308 (nicht beides angeben)

301 und 308 merken sich Browser und Suchmaschinen dauerhaft. Nimm für Weiterleitungen, die sich noch ändern können, "permanent": false.

Platzhalter

Platzhalter in `source`	passt auf	Beispiel
`:name`	genau einen Abschnitt	`/blog/:slug` passt auf `/blog/hallo`, nicht auf `/blog/a/b`
`:name?`	einen oder keinen Abschnitt	`/team/:name?` passt auf `/team` und `/team/anna`
`:name*`	beliebig viele Abschnitte, auch keinen	`/docs/:path*` passt auf `/docs`, `/docs/a` und `/docs/a/b.html`
`:name+`	mindestens einen Abschnitt	`/files/:rest+` passt auf `/files/a/b`, nicht auf `/files`

Im Ziel setzt du den Platzhalter mit seinem Namen ein, mit oder ohne Zeichen dahinter: /news/:slug oder /neu/:path*. Platzhalter mit * und + stehen nur am Ende von source, ein Platzhalter füllt immer einen ganzen Abschnitt (zwischen zwei /).

So wird verglichen

Reihenfolge: Die erste passende Weiterleitung gewinnt. Schreib genaue Regeln vor allgemeine (/blog/erster vor /blog/:slug).
Vor den Dateien: Eine Weiterleitung gilt auch dann, wenn es unter dem Pfad eine Datei gibt.
Query: Die Query der Anfrage wird angehängt: /docs/a?x=1 wird zu https://docs.example.de/a?x=1. Hat das Ziel schon eine Query, kommt sie mit & dazu. Ein Ziel mit Anker (#teil) bekommt keine Query.
Groß- und Kleinschreibung zählt, wie bei Vercel: /Blog passt nicht auf /blog.
/ am Ende ist egal: /alt passt auch auf /alt/.
Passwortschutz: Ist dein Projekt geschützt, leitet gooddeploy erst nach Passwort oder Freigabelink weiter.
Nie weitergeleitet werden /.well-known/… (wie bei Vercel) und die eigenen Pfade von gooddeploy unter /__gooddeploy/, auch nicht mit /:path*.

Prüfung beim Deploy

deploy prüft die Weiterleitungen, bevor gebaut wird. Ein Fehler nennt die Stelle in der Datei, z. B.:

✗ gooddeploy.json: redirects[1].destination: Schleife: /alt → /neu → /alt
  → Prüfe gooddeploy.json.
  Code CONFIG_INVALID · Exit 1

Abgelehnt werden unter anderem:

Schleifen, z. B. /a auf /a oder /a → /b → /a, und Ketten mit mehr als 10 Weiterleitungen (etwa /:path* auf /neu/:path*, das immer wieder passt),
eigene reguläre Ausdrücke wie /(.*) oder /:id(\d+) (nimm :path* bzw. :id),
Ziele ohne / oder https:// am Anfang, Ziele mit // am Anfang und Platzhalter im Hostnamen des Ziels,
ein Platzhalter mit ? oder * vorn im Ziel, wenn danach noch etwas folgt (z. B. /:lang?/:slug): Leer ergäbe das //…, und der Browser ginge auf eine fremde Seite. /:path* allein ist erlaubt,
Leerzeichen, Anführungszeichen, \, $, {, } oder ; in source oder destination (Sonderzeichen schreibst du kodiert, z. B. %20),
mehr als 500 Weiterleitungen, mehr als 512 Zeichen je source bzw. destination oder mehr als 8 Platzhalter in einer Regel.

Auf älteren Plattform-Ständen prüft gooddeploy erst zu Beginn des Builds; die Meldung kommt dann mit BUILD_FAILED.

Next.js

Für Next.js-Apps gelten die Weiterleitungen aus redirects() in deiner next.config.js (bzw. next.config.mjs oder next.config.ts); sie funktionieren bei gooddeploy unverändert. redirects in der gooddeploy.json lehnt deploy bei Next.js mit CONFIG_INVALID und einem Hinweis darauf ab.

Ausnahme: Mit output: "export" baut Next.js nur statische Dateien, und redirects() wirkt dort nicht. Dann trägst du die Weiterleitungen wie oben in die gooddeploy.json ein.

Umzug aus der vercel.json

Kopiere das Array redirects aus der vercel.json in die gooddeploy.json. source, destination, permanent und statusCode bedeuten dasselbe. Prüfe dabei:

In der `vercel.json`	In der `gooddeploy.json`
`"source": "/(.*)"` mit `"destination": "/neu/$1"`	`"source": "/:path"` mit `"destination": "/neu/:path"`
`"source": "/blog/(.*)"`	`"source": "/blog/:path*"`
`"source": "/posts/:id(\\d+)"`	`"source": "/posts/:id"` (ohne Prüfung auf Ziffern)
`"has"` oder `"missing"` (Header, Cookie, Host, Query)	gibt es nicht; solche Regeln bleiben weg
Platzhalter mitten im Abschnitt, z. B. `/blog-:slug`	gibt es nicht; ganze Abschnitte nutzen

Andere Felder der vercel.json (rewrites, headers, trailingSlash, routes) übernimmt gooddeploy nicht. Für cleanUrls: true setzt du "cleanUrls": true in der gooddeploy.json, für eine Single-Page-App "spa": true.

Danach gooddeploy deploy und in der Preview ein paar alte Adressen aufrufen, z. B. im Terminal:

curl -sI https://<preview-adresse>/blog/hallo | grep -i -e '^HTTP' -e '^location'

Ist die Preview geschützt, öffne die Adressen im Browser, nachdem du den Freigabelink aus deploy geöffnet hast. Mehr zum Umzug einer ganzen Next.js-App steht unter Umzug von Vercel.

Quellen zu Vercel

Format von redirects aus der Doku von Vercel, abgerufen am 22.10.2026: Static Configuration with vercel.json (https://vercel.com/docs/project-configuration/vercel-json#redirects) und Configuration Redirects (https://vercel.com/docs/routing/redirects/configuration-redirects). Vercel ist eine Marke der Vercel Inc.