Flutter 3.47 iOS-Upgrade: Remote-Mac-Migrationsliste 2026

Was sich bei der Abhängigkeitsmigration tatsächlich ändert

Seit Flutter 3.44 verwendet Flutter laut offizieller Ankündigung standardmäßig Swift Package Manager für native iOS- und macOS-Abhängigkeiten. Für Abhängigkeiten, die diese Integrationsform noch nicht unterstützen, bleibt jedoch ein CocoaPods-Rückfall erhalten (Flutter-Ankündigung zu Swift Package Manager ab 3.44). Das ist keine Anweisung, jede Podfile sofort zu löschen.

Für die Entscheidung sind drei Ebenen zu trennen:

• Abhängigkeit: Wird ein Plugin über Swift Package Manager, CocoaPods oder beide Wege eingebunden?
• Projektstruktur: Handelt es sich um ein Standardprojekt, ein Projekt mit eigenen Targets, mehrere Flavors oder add-to-app?
• Auslieferung: Funktionieren nicht nur Debug-Simulationen, sondern auch echte Geräte, Archive, Export und der nicht-interaktive CI-Lauf?

Die häufigste Fehlentscheidung besteht darin, nur auf die Existenz einer Podfile zu schauen. Eine vorhandene Podfile beweist nicht, dass die Migration fehlgeschlagen ist; eine entfernte Podfile beweist umgekehrt nicht, dass alle nativen Abhängigkeiten korrekt aufgelöst werden. Entscheidend sind die konkrete Auflösungsquelle, die erzeugten Xcode-Projektänderungen und ein reproduzierbarer Release-Build.

Muss ein iOS-Projekt nach dem Upgrade zwingend auf Swift Package Manager wechseln?
Nein. Ein Standardprojekt kann die neue Standardintegration übernehmen, während für noch nicht kompatible Plugins ein CocoaPods-Rückfall bestehen bleibt. Die richtige Entscheidung wird pro Plugin und Build-Konfiguration getroffen, nicht pauschal für das gesamte Repository.

Eintrittskriterien für die sechs Migrationspfade

Vor dem ersten Upgrade wird das Projekt anhand dieser Bedingungen eingeordnet:

• Standardprojekt: Das Repository folgt weitgehend der Flutter-Vorlage und besitzt keine umfangreichen Änderungen im iOS-Runner.
• Gemischtes Altprojekt: Mindestens ein natives Plugin oder eine Bibliothek bleibt auf CocoaPods angewiesen.
• Mehrfachkonfiguration: Es existieren eigene Flavors, Schemes, Build Configurations oder zusätzliche Targets.
• add-to-app: Flutter wird in eine bestehende native iOS-Anwendung eingebettet.
• Remote-Mac-CI: Der Build läuft auf einem entfernten Mac, häufig ohne dauerhaft geöffnete grafische Sitzung.
• Unklarer Zustand: Dokumentation, Lock-Dateien oder bisherige Build-Artefakte reichen nicht aus, um die aktuelle Integration eindeutig zu rekonstruieren.

Ein unklarer Zustand ist selbst ein Grund, die Umschaltung zu verschieben. Ohne bekannten Ausgangspunkt kann ein späterer Fehler nicht zuverlässig der Flutter-Aktualisierung, dem Paket-Resolver, dem Signierungsprofil oder einer veränderten CI-Umgebung zugeordnet werden.

Erste Phase: Ausgangszustand einfrieren und Beweise sichern

Die Migration beginnt nicht mit flutter upgrade, sondern mit einer reproduzierbaren Bestandsaufnahme. Auf dem bisherigen Knoten werden mindestens folgende Informationen gesichert:

• pubspec.yaml und die zugehörige Lock-Datei,
• ios/Podfile, Podfile.lock und alle eigenen Pod-Spezifikationen,
• ios/Runner.xcodeproj oder ios/Runner.xcworkspace,
• vorhandene .xcconfig-Dateien,
• Schemes, Build Configurations und Export-Optionen,
• Flutter- und Dart-Version,
• Xcode-Version,
• der letzte erfolgreiche CI-Build,
• Build-Log, Archive-Pfad und Export-Artefakt,
• verwendete Signing-Identitäten und Provisioning-Profile, ohne geheime Inhalte in das Repository zu übernehmen.

Ein neutraler Ausgangscheck kann beispielsweise so aussehen:

flutter --version
flutter pub deps
git status --short
git rev-parse HEAD
xcodebuild -version

Die Ausgabe wird zusammen mit dem letzten erfolgreichen Build-Log außerhalb des Produktionsverzeichnisses archiviert. flutter pub deps ersetzt keine native Abhängigkeitsprüfung, zeigt aber, welche Flutter-Plugins überhaupt untersucht werden müssen.

Vor dem Upgrade sollte außerdem ein sauberer Referenz-Build ausgeführt werden. Für ein Standardprojekt gehören dazu mindestens ein Simulatorlauf, ein Lauf auf einem echten iOS-Gerät und ein Release- beziehungsweise Archive-Pfad. Apple beschreibt Archive, Export und die anschließende Verteilung in der offiziellen Dokumentation zum Xcode-Veröffentlichungsprozess.

Freigabe-Checkliste für den isolierten Migrationsknoten

Die folgende Checkliste ist das zentrale Entscheidungswerkzeug. Jeder Punkt wird mit Log, Diff oder Artefakt belegt; ein nicht belegter Punkt gilt als offen und nicht als bestanden.

• [ ] Flutter-Version und Xcode-Version des Ausgangsknotens sind dokumentiert.
• [ ] Der letzte erfolgreiche Commit, das Archive und das exportierte Paket sind auffindbar.
• [ ] pubspec.yaml, Lock-Dateien, Podfile, Podfile.lock und eigene Konfigurationen sind gesichert.
• [ ] Für jedes native Plugin ist der vorgesehene Auflösungsweg festgehalten.
• [ ] Swift Package Manager löst alle dafür vorgesehenen Pakete im tatsächlichen Release-Target auf.
• [ ] Für weiterhin erforderliche CocoaPods-Abhängigkeiten existiert eine getestete Rückfallanweisung.
• [ ] Jedes Flavor und jedes eigene Target besitzt ein geprüftes Scheme und eine passende Build Configuration.
• [ ] Ein Simulatorlauf und ein Lauf auf einem echten Gerät sind erfolgreich.
• [ ] Für jedes relevante Releaseziel wurde ein Archive erzeugt.
• [ ] Das Archive wurde mit der vorgesehenen Signing-Identität exportiert.
• [ ] Der Build funktioniert über SSH ohne interaktive grafische Sitzung.
• [ ] Clean Build und Cache Build liefern erwartbare Ergebnisse.
• [ ] Umgebungsvariablen, Keychain-Zugriff und Cache-Pfade sind im CI-Kontext verfügbar.
• [ ] Der Knoten arbeitet nach einem Neustart erneut mit demselben Prüfpfad.
• [ ] Die Wiederherstellung des bisherigen Produktionszustands wurde zumindest einmal nachvollziehbar vorbereitet.

Die Umschaltregel ist bewusst streng:

• Wenn alle Punkte bis einschließlich Export erfüllt sind, kann der Migrationskandidat für die CI-Prüfung freigegeben werden.
• Wenn nur ein Plugin den neuen Paketweg nicht unterstützt, wird der gemischte Betrieb gewählt; CocoaPods bleibt bestehen.
• Wenn Flavor, eigenes Target oder add-to-app nicht vollständig geprüft ist, bleibt der Produktionsknoten unverändert.
• Wenn Signierung, Archive, SSH-Lauf oder Neustart-Recovery scheitern, erfolgt ein Rückfall auf den bisherigen Buildzustand.
• Wenn die Ursache nicht eindeutig reproduzierbar ist, wird nicht gleichzeitig ein Plugin ersetzt und Flutter aktualisiert.

Standardprojekt: generierte Änderungen beobachten statt nachbauen

Bei einem Projekt nahe an der Standardvorlage sollte Flutter 3.47 zunächst in einer isolierten Arbeitskopie eingesetzt werden. Ziel ist nicht, jede neue Datei manuell nach einem Blogbeispiel zu erstellen, sondern die von Flutter und Xcode erzeugten Änderungen sichtbar zu machen.

Ein kontrollierter Ablauf sieht so aus:

1. Einen separaten Branch oder einen geklonten Arbeitsstand erzeugen.
2. Flutter 3.47 entsprechend der im Team festgelegten Installationsmethode aktivieren.
3. Abhängigkeiten auflösen und den ersten Build ohne manuelle Änderungen an der iOS-Projektdatei starten.
4. Den Git-Diff unmittelbar nach der Generierung prüfen.
5. Geänderte Projektdateien, Build-Phasen, Framework-Vorbereitung und Paketverknüpfungen einzeln bewerten.
6. Simulator, echtes Gerät, Archive und Export mit demselben Commit ausführen.

Die entscheidende Beobachtung ist, ob die Swift-Paketabhängigkeiten im verwendeten Target und in der jeweiligen Konfiguration tatsächlich verfügbar sind. Ein erfolgreicher Simulatorlauf kann native Codepfade, Signierung oder gerätespezifische Bibliotheken unberührt lassen. Deshalb gehören die Ausgaben der Builds zu den Migrationsbeweisen, nicht nur ein grüner lokaler Debug-Start.

Wie lässt sich die neue Swift-Package-Manager-Integration im Projekt prüfen?
Prüfen Sie den Git-Diff, die Xcode-Projektdatei, die Paketauflösung und die Build-Logs gemeinsam. Die Flutter-Anleitung für App-Entwickler beschreibt die vorgesehene Einbindung und ihre Projektgrenzen (Flutter-Leitfaden für Swift Package Manager). Erst wenn das tatsächlich verwendete Target die Pakete in Debug und Release auflösen kann, ist der Standardpfad belastbar.

Die Commit-Grenze muss ebenfalls bewusst festgelegt werden. Generierte Dateien, die Flutter für den Build benötigt, dürfen nicht versehentlich ignoriert werden. Umgekehrt sollten lokale Benutzerzustände, geheime Signierungsdaten und maschinenspezifische Pfade nicht als vermeintliche Migrationslösung eingecheckt werden. Der Vorher-nachher-Diff ist hier ein Freigabedokument: Jede Änderung braucht eine Begründung und einen Rückweg.

Gemischte Projekte: CocoaPods als kontrollierten Rückfall behalten

Ein Projekt mit CocoaPods ist nach dem Upgrade nicht automatisch veraltet. Wenn ein Plugin Swift Package Manager noch nicht unterstützt, kann Flutter auf CocoaPods zurückgreifen. Die konkrete Kompatibilität muss jedoch je Plugin geprüft werden; eine allgemeine Kompatibilitätsliste wäre für eine Releaseentscheidung nicht belastbar.

Für jedes native Plugin wird eine kleine Prüfnotiz angelegt:

• Name und verwendete Version,
• Auflösungsweg: Swift Package Manager, CocoaPods oder Mischform,
• Ergebnis der Paketauflösung,
• erzeugte native Bibliothek beziehungsweise Framework-Struktur,
• minimale iOS-Anforderung laut Projekt- und Bibliothekskonfiguration,
• verwendete Build Configurations,
• Ergebnis von Simulator-, Geräte- und Archive-Build,
• Entscheidung: beide Wege behalten, Plugin ersetzen oder Upgrade verschieben.

Kann ein Flutter-iOS-Projekt weiterhin CocoaPods verwenden?
Ja, sofern ein konkretes Plugin diesen Weg benötigt und der daraus entstehende Build reproduzierbar funktioniert. Die Podfile wird nicht aus Prinzip entfernt. Sie bleibt so lange Bestandteil des Rückfallpfads, bis alle relevanten Plugins auf dem tatsächlichen Releaseweg geprüft sind.

Typische Fehler entstehen, wenn die Migration nur mit einer Bereinigung getestet wird:

flutter clean
rm -rf ios/Pods ios/Podfile.lock
flutter pub get

Diese Befehle können bei einer Diagnose sinnvoll sein, verändern aber den Auflösungszustand und sind kein Beweis für eine erfolgreiche Migration. Für einen Vergleich werden deshalb sowohl ein sauberer Lauf als auch ein Lauf mit dem vorgesehenen Cache dokumentiert. Die Lock-Dateien werden nicht gelöscht, bevor geklärt ist, ob sie Teil der Reproduzierbarkeit sind.

Die Entscheidungsbedingungen lauten:

• Wenn alle benötigten Plugins im Release-Target über Swift Package Manager aufgelöst werden und Geräte- sowie Archive-Build erfolgreich sind, dann kann die neue Integration als Zielpfad freigegeben werden.
• Wenn einzelne Plugins nur über CocoaPods funktionieren, dann bleibt der gemischte Betrieb bestehen und wird im Repository dokumentiert.
• Wenn der Resolver zwar erfolgreich durchläuft, aber ein natives Target beim Kompilieren oder Archivieren scheitert, dann wird nicht auf den neuen Pfad umgeschaltet.
• Wenn ein Plugin ersetzt werden kann, ohne öffentliche Schnittstellen oder Signierungsabläufe zu verändern, dann wird der Ersatz separat getestet, nicht zusammen mit dem Flutter-Upgrade unkontrolliert eingeführt.
• Wenn die Ursache nach Bereinigung und reproduzierbarem Neuaufbau nicht eindeutig ist, dann bleibt der Produktionsknoten auf dem alten Stand.

Mehrere Flavors und eigene Targets separat abnehmen

Bei mehreren Flavors reicht ein erfolgreicher Runner-Debug-Build nicht aus. Jede Konfiguration kann eigene Bundle-Identifier, Signing-Einstellungen, Info-Plists, Schemes, Ressourcen oder native Abhängigkeiten besitzen.

Für jedes Flavor werden deshalb folgende Nachweise gesammelt:

• zugeordnetes Scheme,
• zugehörige Build Configuration,
• Bundle-Identifier,
• Paket- und Framework-Auflösung,
• Flutter- beziehungsweise Vorbereitungs-Skript,
• Signierungsidentität und Profilzuordnung,
• Testlauf,
• Archive-Ausgabe,
• exportiertes Paket und Zielpfad.

Wie wird ein Flutter-Projekt mit mehreren Flavors für Swift Package Manager geprüft?
Jedes Flavor wird wie ein eigenes Releaseziel behandelt. Zuerst wird die Paketverfügbarkeit im betreffenden Target geprüft, anschließend werden Test, Archive und Export mit genau diesem Scheme ausgeführt. Ein grüner Standard-Runner darf staging oder production nicht stellvertretend freigeben.

Ein möglicher Prüfablauf muss an die im Projekt vorhandenen Scheme-Namen angepasst werden:

flutter build ios --release --flavor staging
flutter build ios --release --flavor production
xcodebuild -list -workspace ios/Runner.xcworkspace

Die Befehle sind nur Beispiele für den Prüfmechanismus; die tatsächlichen Workspace-, Scheme- und Exportparameter werden aus dem Repository übernommen. Für ein eigenes Target ist zusätzlich zu prüfen, ob die generierten Swift-Package-Abhängigkeiten wirklich mit diesem Target verbunden sind. Eine Zuordnung, die nur für Runner gilt, reicht nicht für eine App mit Widget, Notification Extension oder eigener Host-Anwendung.

add-to-app: den nativen Host als eigene Migration behandeln

Flutter add-to-app unterscheidet sich strukturell von einer reinen Flutter-iOS-Anwendung. Der native Host besitzt eigene Abhängigkeiten, Startlogik, Ressourcen und Build-Konfigurationen. Eine alte Einbindung über Frameworks oder CocoaPods darf deshalb nicht ungeprüft mit der neuen Paketstrategie kombiniert werden.

Die offizielle Flutter-Dokumentation zu add-to-app unter iOS dient als Referenz für die unterstützte Projektstruktur. Im konkreten Host-Projekt werden zusätzlich diese Punkte geprüft:

• Wie wird das Flutter-Modul eingebunden und initialisiert?
• Welche native Abhängigkeit gehört zum Host und welche zum Flutter-Modul?
• Werden Flutter-Ressourcen in Debug und Release korrekt gepackt?
• Sind alle Host-Schemes und Exportoptionen berücksichtigt?
• Gibt es doppelte Framework-, Pod- oder Paketverknüpfungen?
• Startet eine native Seite das Flutter-Modul auch nach einer sauberen Installation?
• Kann der alte Integrationsstand wiederhergestellt werden?

Was muss nach einem add-to-app-Upgrade bei den nativen Abhängigkeiten kontrolliert werden?
Die Prüfung beginnt beim Host-Projekt, nicht bei einer isolierten Flutter-Demo. Es werden Paketquellen, Modulinitialisierung, Ressourcen und Konfigurationen getrennt erfasst. Danach müssen mindestens ein Start des Flutter-Moduls aus einer nativen Seite, ein Release-Build und eine Wiederherstellung der alten Integration erfolgreich sein.

Die Rückfallübung ist wichtig, weil ein add-to-app-Fehler erst spät sichtbar werden kann: Der Flutter-Teil kompiliert, aber der Host findet beim Linken eine Bibliothek nicht oder lädt Ressourcen aus einem falschen Bundle. Solche Fehler werden durch einen isolierten Flutter-Debuglauf nicht erkannt.

Remote Mac und CI-Knoten: reproduzierbare Übergabe statt grafischer Einzelerfolg

Ein Remote Mac ist für die Migration sinnvoll, wenn er einen getrennten Buildzustand bereitstellt und nicht als unkontrollierte Kopie des Produktionsknotens verwendet wird. Der technische Zugriff kann über SSH erfolgen; entscheidend ist jedoch, dass der gleiche Ablauf auch ohne geöffnete Xcode-Oberfläche funktioniert.

Der Knoten wird zunächst mit festgelegten Versionen und Verzeichnissen vorbereitet:

1. Einen eigenen Benutzer oder ein klar abgegrenztes Arbeitsverzeichnis für den Migrationslauf einrichten.
2. Flutter-, Dart- und Xcode-Version ausgeben und im Build-Log speichern.
3. Repository mit identischem Commit auschecken.
4. Abhängigkeits-Lock-Dateien und Cache-Strategie festlegen.
5. SSH-Befehl ohne interaktive Shell ausführen.
6. Umgebungsvariablen, Schlüsselzugriff und temporäre Pfade prüfen.
7. Clean Build und Cache Build getrennt ausführen.
8. Geräte-Signierung, Archive und Export ausführen.
9. Den Knoten neu starten und denselben Prüfpfad erneut anstoßen.
10. Erst nach dokumentierter Freigabe den Produktionsknoten ersetzen.

Ein nicht-interaktiver Test kann beispielsweise so aussehen:

ssh builduser@remote-mac 'cd /path/to/project && \
  flutter --version && \
  flutter pub get && \
  flutter build ios --release'

Der konkrete Pfad und Benutzername müssen durch die tatsächliche Infrastruktur ersetzt werden. Im Log wird kontrolliert, ob PATH, Flutter-SDK, Zertifikatszugriff, Keychain-Freigaben, Cache-Verzeichnisse und Arbeitsverzeichnis auch ohne grafische Sitzung vorhanden sind. Ein Build, der nur nach manuellem Öffnen von Xcode funktioniert, ist für CI nicht abgenommen.

Für Archive und Export gelten die Apple-Vorgaben zu Archive und Export in Xcode. Die Signierungsidentitäten und Team-Zertifikate müssen nach dem Prinzip der geringsten Berechtigung verwaltet werden; Apple beschreibt dazu den Umgang mit gemeinsam verwendeten Signing-Zertifikaten. Secrets gehören weder in Shell-History noch in Build-Logs. Bei einem Remote-Knoten sind außerdem DSGVO-relevante Fragen zu Quellcode, Kundendaten, Protokollen und Zugriffsschlüsseln vor der produktiven Nutzung zu dokumentieren.

Wie wird ein Remote Mac für Flutter-iOS-Archive und Signierung abgenommen?
Nicht durch einen einzelnen erfolgreichen SSH-Befehl. Der Knoten muss denselben Commit in sauberem und gecachtem Zustand bauen, ein echtes Archive erzeugen, es mit der vorgesehenen Identität exportieren und nach einem Neustart erneut reproduzierbar arbeiten. Erst danach ist er als Produktionskandidat geeignet.

Die Umschaltentscheidung anhand von vier Nachweisen

Die Freigabe wird als kurze Entscheidungsmatrix geführt, ohne eine pauschale Aussage über alle Projekte zu erzwingen:

• Wenn Standardprojekt, Geräte-Build, Archive, Export und CI-Lauf erfolgreich sind, dann kann auf Flutter 3.47 umgeschaltet werden.
• Wenn CocoaPods für einzelne Plugins weiterhin erforderlich ist, dann wird der gemischte Betrieb mit dokumentierter Lock-Datei und Rückfallanweisung freigegeben.
• Wenn ein Flavor, Target oder add-to-app-Host abweicht, dann gilt die Migration erst nach separater Konfigurationsprüfung als bestanden.
• Wenn Signierung, Archive, SSH-Lauf oder Neustart-Recovery scheitern, dann bleibt der bisherige Knoten aktiv und der neue Knoten wird diagnostiziert.
• Wenn der alte Build nach der Umstellung nicht innerhalb des festgelegten Rückfallfensters wiederherstellbar ist, dann erfolgt keine Produktionsumschaltung.
• Wenn keine isolierte Hardware vorhanden ist, dann sollte zunächst für einen vollständigen Veröffentlichungszyklus ein unabhängiger Remote Mac bereitgestellt werden, bevor der bestehende CI-Knoten verändert wird.

Für Teams ohne eigene Reservehardware kann ein Mac-mini-Mietmodell für Entwicklungs- und Buildaufgaben die isolierte Testphase ermöglichen. Für die Standortplanung stehen außerdem die verfügbaren Mac-mini-Optionen bereit; maßgeblich bleibt, ob der gewählte Knoten den benötigten SSH-, Keychain- und CI-Ablauf reproduzierbar unterstützt.

Aktuelle Lösung und Remote-Mac-Variante realistisch abwägen

Wer den bestehenden Produktionsknoten direkt aktualisiert, spart zunächst den Aufbau einer Testumgebung, trägt aber mehrere konkrete Nachteile: Ein fehlerhaftes Plugin kann laufende Releases blockieren, ein veränderter Paket-Resolver erschwert den Vergleich mit dem letzten funktionierenden Build, und ein beschädigter Cache kann den Fehler nur auf einem einzelnen Rechner erzeugen. Bei einem lokalen Mac kommen zusätzlich die Bindung von Hardware, Wartungsfenster und die begrenzte Verfügbarkeit für parallele Tests hinzu.

Ein separat gemieteter Remote Mac bietet in diesem Szenario die bessere Ausweichroute, wenn kurzfristig ein echter macOS-Knoten mit vollständigen Rechten benötigt wird. Er kann für die Migrationsphase neben dem bisherigen System laufen, gezielt zurückgesetzt oder nach bestandener Prüfung wieder freigegeben werden. Das ist besonders dann sinnvoll, wenn kein zweiter physischer Mac verfügbar ist und die Pipeline nicht für mehrere Tage unterbrochen werden darf.

Für langfristig konstante Hochlast, spezielle physische Geräte oder dauerhaft benötigte lokale Peripherie kann der Kauf eines eigenen Mac weiterhin die passendere Lösung sein. Für eine zeitlich begrenzte Flutter-3.47-Prüfung mit Remote-Zugriff, CI-Tests und anschließendem Rückfall ist eine gemietete NodeMini-Mac-Umgebung jedoch meist der kontrolliertere Weg, weil die Produktionsmaschine unangetastet bleibt, bis die Migrationsnachweise vollständig vorliegen.