Upgrade auf Go 1.27: Was bricht, was als erstes übernommen werden sollte

Go 1.27 wurde im August 2026 veröffentlicht. Für die meisten Module ist der Upgrade ein einziger go.mod-Eintrag, gefolgt von einem go fix-Lauf — aber einige Änderungen treffen still und heimlich zu. Hier ist, was tatsächlich kaputtgeht und was zuerst adaptiert werden sollte.

Die wichtigsten Änderungen sind struktureller Natur: encoding/json wird jetzt unter der Haube durch die neue json/v2-Implementierung bereitgestellt, das uuid-Paket kam in die Standardbibliothek, und Methoden können endlich ihre eigenen Typparameter deklarieren. Keine dieser Änderungen erzwingt einen Neuschreib-Vorgang, und das Go-Team hat das übliche Kompatibilitätsversprechen eingehalten — fast alles kompiliert und läuft unverändert.

Nicht alles ist jedoch ruhig. Mehrere GODEBUG-Einstellungen führen bei ihren alten Werten jetzt zu Build-Fehlern, compress/flate erzeugt andere Bytes, go test erzwingt eine neue stdversion-Prüfung, und die von der Kompilierer erzeugten Symbolnamen haben sich geändert. Wer einen Auffrischungsschub in der Syntax für die Teile braucht, die sich nicht verändert haben, für den gilt weiterhin der Go-Spickzettel; dieser Leitfaden deckt den Rest ab, mit Befehlen und Korrekturen für jeden Punkt.

Der Upgrade-Pfad in einem Diagramm

Das Go-Team empfiehlt die Reihenfolge „erst bauen, dann beheben". go fix schreibt Code auf neue APIs und Idiome um, aber nur ein sauberer Build sagt, ob Sie von den Änderungen auf Runtime-Ebene betroffen sind.

Beginnen Sie mit der Toolchain selbst. Wenn Sie Toolchains über den go-Befehl verwalten, können Sie die Version entweder in go.mod festpinnen oder sie explizit installieren:

go install golang.org/dl/go1.27@latest
go1.27 download
go1.27 version

Alternativ setzen Sie GOTOOLCHAIN=go1.27.0 in der Umgebung oder fügen Sie toolchain go1.27.0 zu go.mod hinzu, damit der go-Befehl sie herunterlädt. Der modulbezogene Begleiter-Artikel zur Go-Workspace-Struktur erklärt, wie die go- und toolchain-Zeilen über mehrere Module hinweg miteinander interagieren; die Kurzversion für ein einzelnes Modul finden Sie unten.

Schritt 1: go-Zeile erhöhen und entfernte GODEBUG-Einstellungen aufräumen

go mod edit -go=1.27
go mod tidy
go build ./...

Das Erhöhen der go-Direktive schaltet die neuen Sprachfunktionen ein (generische Methoden, Schlüssel für hochgezogene Felder in Struct-Literalen, breitere Typermittlung für Funktionen) und macht den go-Befehl streng gegenüber GODEBUG-Einstellungen, deren Unterstützung entfernt wurde. Go 1.27 hat diese dauerhaft entfernt:

• asynctimerchan — Timer- und Ticker-Kanäle sind jetzt immer nicht gepuffert
• gotypesalias
• tlsunsafeekm, tlsrsakex, tls3des, tls10server
• x509keypairleaf

Die neue Regel: Der go-Befehl akzeptiert diese Einstellungen in go.mod (godebug-Einträge) oder im Quellcode (//go:debug-Kommentare), wenn sie auf den finalen Standardwert gesetzt sind, der vor der Entfernung existierte. Ein alter Wert — der eine Verhaltensänderung deaktiviert hatte — lässt den Build fehlschlagen:

//go:debug asynctimerchan=0  // Build-Fehler: alter Wert einer entfernten Einstellung
//go:debug asynctimerchan=1  // akzeptiert, aber besser die Zeile löschen

Wenn Ihr Build hier fehlschlägt, hat der Code vor Go 1.23 gepufferte Timer-Kanäle vorausgesetzt. Die Lösung liegt im Code, nicht in der Konfiguration: Prüfen Sie die Verwendung von Timer.Stop und Timer.Reset anhand der Mustervorgänge für Kontexte, Abbruch und Timeouts, die auf den synchronen Kanälen basieren. Dieselbe Suche gilt für die TLS-bezogenen Einstellungen — alles, was tls3des=1 oder tls10server=1 festlegte, hielt alte Chiffresuiten am Leben, und Go 1.27 weigert sich, es zu kompilieren.

Schritt 2: go test ausführen — die stdversion-Falle

go build und go test sind sich nicht länger einig. Das go test von Go 1.27 führt die stdversion-vet-Prüfung standardmäßig aus, die Standardbibliothek-Symbole meldet, die für die in der referenzierenden Datei geltende go-Version zu neu sind.

// go.mod sagt immer noch "go 1.26"
func Base(p string) string {
    _, file, ok := strings.CutLast(p, "/") // hinzugefügt in Go 1.27
    if !ok {
        return p
    }
    return file
}

Mit einer 1.27-Toolchain ist go build erfolgreich — der Kompilierer hat strings.CutLast — während go test den vet-Schritt fehlschlägt, weil go.mod immer noch 1.26 deklariert. Mit einer echten 1.26-Toolchain würde die Datei gar nicht erst gebaut. Die Lektion ist prozedural: Validieren Sie einen Upgrade niemals nur mit go build; führen Sie den vollständigen Testsatz aus, erhöhen Sie dann die go-Zeile. Der vet-Satz in go test hat auch einen neuen printf-Befund aufgenommen: fmt.Errorf("...: %w", p), wobei p ein *E ist und E error implementiert, warnt jetzt, weil das Einwickeln eines Zeigers zu Typ-Assertions und errors.Is-Prüfungen führt, die fehlschlagen. Dieser Fehlschlagsmodus tritt im Fehlerbehandlung-Code genau so auf, wie er in den Mustern zur Go-Fehlerbehandlungs-Architektur beschrieben ist — prüfen Sie den Operanden-Typ, nicht nur den Verb.

encoding/json: die v2-Maschinerie darunter

Die größte Änderung unter der Haube: encoding/json/v2 (seit Go 1.25 experimentell als GOEXPERIMENT=jsonv2) ist ausgereift, und das klassische encoding/json-Paket wird jetzt durch die v2-Implementierung bereitgestellt. Für v1-Aufrufe bleibt das Verhalten erhalten — nil-Slices werden immer noch als null kodiert, Map-Keys werden immer noch sortiert — mit einem sichtbaren Unterschied: Der exakte Text einiger Fehlermeldungen hat sich geändert. Wenn Tests oder Überwachung auf Fehlerstrings abgleichen, ist mit Diffs zu rechnen.

Drei Dinge können immer noch schiefgehen:

1. Fehlertext. Jegliche strings.Contains(err.Error(), ...)-Assertions, die auf die alte v1-Wortwahl ausgerichtet sind, müssen aktualisiert werden.
2. Performance-kritische Pfade können sich verschieben. Das Unmarshalling ist schneller, aber das Umgeschrieben ändern, welche Operationen Speicher allozieren; in CI markierte Benchmarks werden es zeigen.
3. Kompatibilitäts-Schnellweg. GOEXPERIMENT=nojsonv2 stellt die ursprüngliche v1-Implementierung zur Build-Zeit wieder her. Es ist temporär — planen Sie, es zu entfernen, nicht damit zu liefern.

Ein sekundäreffekt für Golden-Tests: Der Kodierer von compress/flate hat sich in derselben Version geändert, daher können Ausgaben von archive/zip, compress/gzip, compress/zlib und image/png byte für byte von Go 1.26 abweichen, auch wenn sie identisch dekodiert werden. Erzeugen Sie komprimierte Fixtures neu, statt alte Bytes festzulegen.

Gezielter Migrationsweg zur v2-API

Die v2-API ist ein separater Import (encoding/json/v2) mit Marshal, Unmarshal und einem Optionensystem. Der unterstützte Migrationspfad besteht darin, v2-Aufrufe zuerst so zu verhalten wie v1, dann selektiv zu verschärfen:

import (
    "encoding/json/v2"
    "encoding/json/jsontext"
)

// Schritt 1: identisches Verhalten wie encoding/json — eine sichere, mechanische Änderung
out, err := jsonv2.Marshal(v, jsonv2.DefaultOptionsV1())

// Schritt 2: Schritt für Schritt auf einen v2-Standard umsteigen
out, err := jsonv2.Marshal(v,
    jsonv2.DefaultOptionsV1(),
    jsonv2.FormatNilSliceAsNull(false)) // nil-Slices werden jetzt als [] kodiert

Sobald Sie DefaultOptionsV1 fallen lassen, gelten die v2-Defaults, die strenger und besser interoperabel sind als v1:

Die unsortierten Map-Keys sind das, was Golden-File-Tests überrascht: v2 überspringt die Sortierung, weil Sortierung Zeit kostet. Wenn Sie stabile Ausgaben benötigen — Fixtures, Snapshot-Tests, gehashte Darstellungen — übergeben Sie json.Deterministic(true), das sortierte Ausgaben für Maps und Structs wiederherstellt. Die Modelle im Vergleichs-Artikel über ORMs tragen alle json-Tags; diese Tags funktionieren in v2 weiterhin, aber die format-Tag-Option wurde während des Experiments entfernt und inline wurde in embed umbenannt, daher die Modelldefinitionen nach beiden durchsuchen, bevor Sie migrieren. Für Low-Level-Bedarfe — Streaming, tokenweise Verarbeitung, benutzerdefinierte Syntaxbehandlung — bietet das Begleit-Paket encoding/json/jsontext eine Encoder/Decoder-Zustandsmaschine über JSON-Text.

stdlib uuid: github.com/google/uuid ablösen

Go 1.27 fügt uuid zur Standardbibliothek hinzu und implementiert RFC 9562. Die API-Abdeckung umfasst die üblichen Fälle:

id := uuid.New()    // aktuell äquivalent zu NewV4
v7 := uuid.NewV7()  // zeit-sortierbar, 48-Bit-Zeitstempel + Zufall
u, err := uuid.Parse("550e8400-e29b-41d4-a716-446655440000")

github.com/google/uuid ist das am zweithäufigsten abhängige Go-Modul, daher ist diese Migration im großen Maßstab wichtig. Die beiden APIs sind nah beieinander — Typen sind [16]byte-Werte, vergleichbar mit == und verwendbar als Map-Keys, String(), MarshalText/UnmarshalText round-trip — und das Upstream-Projekt bereitet go:fix inline-Shims vor, damit go fix uuid.NewV4()-Aufrufe auf das Standardpaket umschreiben und die Abhängigkeit entfernen kann.

Die interessante Adoptionsentscheidung ist NewV7. Version-7-UUIDs beinbetten einen Millisekunden-Zeitstempel in den bedeutendsten Bits, daher sortieren sich die Werte in der Erstellungsreihenfolge (außer wenn die Systemuhr zurückläuft). Für Datenbank-Primärschlüssel bedeutet das bessere B-Tree-Lokalität als zufällige UUIDv4, und eine created_at-ähnliche Ordnung für kostenlos im Identifikator selbst — dieselbe Eigenschaft, die die Diskussion über zeit-sortierbare Schlüssel in Multi-Tenant-Datenmodellen antreibt.

Sprachänderungen: generische Methoden und Freunde

Generische Methoden sind das am meisten gewünschte Sprachfeature der Version: Eine Methodendeklaration darf jetzt ihre eigenen Typparameter deklarieren.

// Go 1.27: math/rand/v2 erhielt eine generische Methode neben der Funktion
func (r *Rand) N[Int intType](n Int) Int

Zwei Einschränkungen halten das Typsystem entscheidbar: Interface-Methoden dürfen keine Typparameter deklarieren, und Interface-Methoden können nicht durch generische Methoden implementiert werden. Daneben dürfen Struct-Literal-Schlüssel jetzt jeder gültige Feldselektor sein (nicht nur Top-Level-Feldnamen), und die Typermittle für Funktionen verallgemeinert sich auf alle Kontexte, in denen eine generische Funktion an eine passende Funktions-Typ-Variable zugewiesen wird. Keine dieser Änderungen bricht vorhandenen Code; sie entfernen Workarounds — paketweite generische Hilfsfunktionen und explizite Instanziierungen.

go fix hat Modernisierer für angrenzende Aufräumungen bekommen: atomictypes, embedlit, slicesbackward und unsafefuncs. Eine Vorsicht aus den praktischen Upgrade-Labs: go fix -fix=atomictypes gezielt und nicht in Massen auf Bibliotheken ausführen, da es die Typen paketweiter Variablen ändern kann, auf die andere Pakete verweisen. Der waitgroup-Modernisierer wurde in waitgroupgo umbenannt; beachten Sie, dass sync.WaitGroup.Go (ab 1.25) bereits die meisten Fälle abdeckt, die er detektiert — siehe die Muster für beschränkte Parallelität, wie es in den Worker-Pool-Shutdown passt.

Dinge, die still und leise kaputtgehen

Das sind die Änderungen, die zwar sauber kompilieren, aber trotzdem einen Release-Tag kosten:

• Symbolnamen von Funktionsliteralen. Der Kompilierer erzeugt jetzt einfachere, von Inlining unabhängige Namen für Closures und kann identische Funktionsliteral zusammenführen. Tests, die über Tracebacks oder Profile auf Symbolnamen prüfen, schlagen fehl; Code, der Funktions-Code-Zeiger auf Gleichheit vergleicht, wird in mehr Fällen offengelegt.
• gofmt-Ausrichtung. Eine Korrektur der Spaltenausrichtungsl Logik (sie variierte zuvor über CPU-Architekturen) fließt eine kleine Anzahl bereits formatierter Dateien neu. Erwarten Sie nur-Weißraum-Diffs in einem gofmt ./...-Commit nach dem Upgrade.
• go mod tidy schreibt go.mod um. Für Module auf go 1.27 verschmilzt tidy jetzt doppelte require-Blöcke in höchstens zwei Blöcke (direkt, indirekt), unter Beibehaltung von Kommentaren. Diffen Sie Ihre go.mod und lösen Sie alle Merge-Konflikt-Reste vor dem Release-Commit, nicht danach.
• Traceback-Labels. Tracebacks für Module auf go 1.27 enthalten runtime/pprof-Goroutine-Labels in der Kopfzeile; deaktivieren Sie mit GODEBUG=tracebacklabels=0, wenn Labels sensible Daten tragen.
• go tool trace bindet an localhost. -http=:6060 lauscht jetzt nur auf localhost; übergeben Sie -http=0.0.0.0:6060 explizit, wenn Sie Remote-Zugriff benötigen (und bedenken Sie, dass ein Profiling-Port auf einem gemeinsamen Host ein Risiko ist — siehe den Produktions-Profiling-Workflows für das gehärtete Setup).

Experiments, die es zu beobachten lohnt

Zwei experimentelle Pakete wurden in 1.27 ausgeliefert, beide zur Build-Zeit mit GOEXPERIMENT=simd aktiviert:

• simd — eine portierbare, vektorgröße-unabhängige API (Int8s, Float32s, …), die auf Hardware-Instruktionen abbildet, wo verfügbar. Es unterstützt AVX/AVX2/AVX-512 auf amd64, NEON auf arm64 und WebAssembly SIMD. Die Standardbibliothek verwendet diese Maschinerie bereits intern: Go’s Swiss Table Map-Implementierung profitiert davon.
• simd/archsimd — die architekturspezifische Schicht für Code, der die Vektorbreite kennen muss.

Auf der Kryptographie-Seite implementiert crypto/mldsa den post-quanten ML-DSA-Signatur-Schema aus FIPS 204 in drei Parametersätzen (MLDSA44, MLDSA65, MLDSA87), integriert in crypto/x509 und angeboten als TLS 1.3-Signatur-Schemas. Hybrid post-quanten Schlüsselabtausch kann jetzt über Config.CurvePreferences erzwungen werden, selbst wenn die tlsmlkem/tlssecpmlkem GODEBUG-Fallbacks gesetzt sind. Keines davon ist heute ein Migrationspunkt, aber beide formen die TLS-Konfigurationsoberfläche, in die Ihre Dienste hineinwachsen werden.

Neue APIs, die sofort adaptiert werden sollten

Einige Zusätze lösen alltägliche Reibung und kosten nichts zu adaptieren:

// strings.CutLast / bytes.CutLast — der LastIndex-Tanz, ersetzt
before, after, found := strings.CutLast("a/b/c.tar.gz", ".")

// httptest.NewTestServer — in-memory Fake-Netzwerk, Auto-Cleanup
srv := httptest.NewTestServer(t, mux) // kein echter Port, kein defer srv.Close()

httptest.NewTestServer erstellt einen httptest.Server, der durch ein In-Memory-Netzwerk statt einen TCP-Listener unterstützt wird und registriert sein eigenes t.Cleanup. Der echte Gewinn ist das Pairing mit testing/synctest: HTTP-Rundenläufe laufen in synthetischer Zeit, was Timeout- und Retry-Tests schnell und deterministisch macht — die Kombination ist im Artikel zu synctest-Konkurrenz-Tests demonstriert.

Upgrade-Checkliste

Die Reihenfolge ist wichtiger als die Punkte; jeder Schritt setzt den vorherigen als grün voraus.

Schließende Anmerkungen

Go 1.27’s Brüche konzentrieren sich um Ränder, die die meisten Programme nie berühren — entfernte GODEBUG-Opt-Outs, Symbolnamen-Assertions, komprimierte Byte-Fixtures — während seine Gewinne dort landen, wo jedes Programm lebt: schnelleres JSON, standardisierte UUIDs, generische Methoden. Ein sauberer Upgrade istmostly Disziplin: go build, dann go test, dann go fix, in dieser Reihenfolge, mit der go-Zeile vor dem Testlauf erhöht statt danach. Der nojsonv2-Schnellweg und die asynctimerchan-Akzeptanz-bei-finalen-Default-Regel kaufen Zeit, aber beide sind zum Verschwinden vorgesehen, daher diesen Upgrade als Frist für die verzögerten Fixes behandeln, die er aus 1.23–1.26 erbt.