Flutter Swift Package Manager: CocoaPods-Migrationsleitfaden

Das Ende von CocoaPods hat begonnen

Am 2. Dezember 2026 wird das CocoaPods trunk-Registry dauerhaft in den Read-Only-Modus versetzt. Das bedeutet, dass weder neue Pods veröffentlicht noch bestehende Pods aktualisiert werden können. Dies ist das faktische Ende des Abhängigkeitsmanagers, auf den sich Flutter-iOS-Entwickler fast ein Jahrzehnt lang verlassen haben.

Das Flutter-Team bereitet die Unterstützung für den Swift Package Manager (SwiftPM) bereits seit 2024 vor. Mit Flutter 3.44 wurde SwiftPM zum Standard-Abhängigkeitsmanager für iOS/macOS. Wenn Sie flutter run ausführen, aktualisiert die Flutter-CLI Ihr Xcode-Projekt automatisch auf SwiftPM-Basis.

Dieser Artikel behandelt zwei Perspektiven:

1. App-Entwickler: So migrieren Sie ein bestehendes CocoaPods-basiertes Flutter-Projekt auf SwiftPM.
2. Plugin-Autoren: So fügen Sie Package.swift hinzu, damit Ihr pub.dev-Plugin SwiftPM unterstützt.

Wenn Sie jetzt nicht migrieren, werden Ihre iOS-Abhängigkeiten nach Dezember 2026 effektiv eingefroren sein.

CocoaPods vs. Swift Package Manager: Die wichtigsten Unterschiede

Der größte Vorteil von SwiftPM ist seine native Integration in Xcode. Es ist kein separates pod install mehr erforderlich, und Sie können direkt mit .xcodeproj statt mit der .xcworkspace-Datei bauen.

App-Entwickler: Automatische Migration

Wenn Sie Flutter 3.44 oder höher verwenden, erfolgt die Migration in den meisten Fällen automatisch.

1. Flutter-Version überprüfen

flutter --version
# Überprüfen, ob Flutter 3.44.0 oder höher installiert ist

flutter upgrade  # Bei Bedarf aktualisieren

2. Automatische Migration auslösen

# Beim Ausführen im bestehenden Projekt versucht die Flutter-CLI automatisch die SwiftPM-Migration
flutter run

# Oder explizit aktivieren
flutter config --enable-swift-package-manager
flutter run  # Übernimmt bei nachfolgenden Ausführungen automatisch die SwiftPM-Konfiguration

Die von der Flutter-CLI durchgeführte automatische Migration umfasst:

1. Hinzufügen von SwiftPM-Integrationseinstellungen zu ios/Runner.xcodeproj/project.pbxproj
2. Hinzufügen einer Referenz auf FlutterGeneratedPluginSwiftPackage im Ordner ios/
3. Hinzufügen von Run Prepare Flutter Framework Script zum Xcode-Build-Schema

3. Erfolgreiche Migration überprüfen

# In Xcode überprüfen
open ios/Runner.xcworkspace

# Oder im Terminal
cat ios/Runner.xcodeproj/project.pbxproj | grep "FlutterGeneratedPluginSwiftPackage"
# Wenn dieser String vorhanden ist, ist die SwiftPM-Integration abgeschlossen

In Xcode werden die Plugins im Tab Project Navigator → Package Dependencies als SwiftPM-Pakete angezeigt.

4. Umgang mit nicht unterstützten Plugins

Wenn Plugins vorhanden sind, die SwiftPM noch nicht unterstützen, gibt die Flutter-CLI eine Warnung aus:

The following packages have native iOS code but are not compatible with Swift Package Manager:
  - some_plugin (version: 1.2.3)

Flutter will use CocoaPods for these plugins only.

In diesem Fall wechselt Flutter automatisch in einen Fallback-Modus: Unterstützte Plugins verwenden SwiftPM, nicht unterstützte Plugins weiterhin CocoaPods. Das Podfile bleibt erhalten und wird nur auf Plugins angewendet, die pod install benötigen.

Vorgehen bei nicht unterstützten Plugins:

1. Erstellen Sie ein Issue für SwiftPM-Unterstützung im GitHub-Repository des Plugins.
2. Suchen Sie nach alternativen Plugins (prüfen Sie die SwiftPM-Unterstützung auf pub.dev).
3. Reichen Sie selbst einen PR mit Package.swift ein.

5. Temporäre Deaktivierung (bei Problemen)

Falls SwiftPM Build-Fehler verursacht, können Sie es vorübergehend deaktivieren:

# pubspec.yaml — Temporäre Deaktivierung
flutter:
  config:
    enable-swift-package-manager: false

Oder:

flutter config --no-enable-swift-package-manager

⚠️ Diese Option ist eine temporäre Ausweichlösung. Sie wird voraussichtlich um 2027 entfernt. Verlassen Sie sich daher nicht darauf.

App-Entwickler: Manuelle Migration (Legacy-Projekte)

Falls die automatische Migration fehlschlägt oder Sie ein älteres Projekt migrieren, führen Sie die Schritte manuell durch.

Checkliste vor der Migration

# Aktuellen Zustand sichern
git checkout -b feat/spm-migration
git add -A && git commit -m "chore: before SPM migration"

# SwiftPM-Unterstützung aller Plugins prüfen
cat pubspec.yaml | grep -A 50 "dependencies:"

Überprüfen Sie auf der pub.dev-Seite jedes Flutter-Plugins das Badge “Swift Package Manager support”.

Podfile bereinigen

# ios/Podfile (bleibt nach der Migration für Fallback-Plugins erhalten)
platform :ios, '13.0'  # Mindest-iOS-Version prüfen

# Nach der SwiftPM-Migration werden unterstützte Plugins automatisch ausgeschlossen
# Nur noch bei Bedarf Plugins angeben, die ausschließlich CocoaPods nutzen
target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))

  target 'RunnerTests' do
    inherit! :search_paths
  end
end

Migration ausführen

cd ios

# Bestehenden CocoaPods-Cache bereinigen
rm -rf Pods/ Podfile.lock

# Flutter Clean
cd ..
flutter clean

# Abhängigkeiten neu installieren (Mischbetrieb SwiftPM + CocoaPods)
flutter pub get
cd ios && pod install  # Für weiterhin benötigte CocoaPods-Plugins
cd ..

# Build testen
flutter build ios --no-codesign

Plugin-Autoren: Package.swift hinzufügen

Wenn Sie ein Flutter-Plugin auf pub.dev veröffentlichen, sollten Sie SwiftPM-Unterstützung hinzufügen. Das pub.dev-Bewertungssystem bezieht die SwiftPM-Unterstützung in die Evaluierung ein, sodass bei fehlender Unterstützung Abzüge drohen.

Verzeichnisstruktur anpassen

Bestehende CocoaPods-Struktur:

ios/
  Classes/
    MyPlugin.swift
    MyPlugin.h (bei Obj-C-Mischbetrieb)
  my_plugin.podspec

Struktur nach SwiftPM-Unterstützung:

ios/
  my_plugin/           # SwiftPM-Paketroot (neu hinzugefügt)
    Package.swift      # SwiftPM-Manifest
    Sources/
      my_plugin/       # Zielname = Paketname
        MyPlugin.swift
  Classes/             # Für CocoaPods-Abwärtskompatibilität beibehalten
    MyPlugin.swift
  my_plugin.podspec    # Bestehendes podspec beibehalten

Bei SwiftPM müssen sich die Quelldateien zwingend innerhalb des Paketroots befinden. Während CocoaPods Pfade außerhalb des Roots erlaubte, setzt SwiftPM dies strikt im Paketinneren voraus.

Package.swift erstellen

Für ein reines Swift-Plugin:

// ios/my_plugin/Package.swift
// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "my_plugin",
    platforms: [
        .iOS(.v13),
    ],
    products: [
        .library(
            name: "my-plugin",
            targets: ["my_plugin"]
        )
    ],
    dependencies: [],
    targets: [
        .target(
            name: "my_plugin",
            dependencies: [],
            path: "Sources/my_plugin",
            // Bei externen Swift-Abhängigkeiten:
            // dependencies: [
            //   .product(name: "SomeSDK", package: "some-sdk"),
            // ]
        )
    ]
)

Für ein gemischtes Swift- und Objective-C-Plugin:

// ios/my_plugin/Package.swift
// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "my_plugin",
    platforms: [
        .iOS(.v13),
    ],
    products: [
        .library(name: "my-plugin", targets: ["my_plugin"])
    ],
    targets: [
        .target(
            name: "my_plugin",
            dependencies: [],
            path: "Sources/my_plugin",
            // Öffentlichen Header-Pfad für Obj-C angeben
            publicHeadersPath: "include",
            // Obj-C-Dateien werden demselben Target hinzugefügt
            cSettings: [
                .headerSearchPath("include"),
            ]
        )
    ]
)

SwiftPM erlaubt keine Mischung von Swift und Objective-C im selben Target. Wenn Ihr Plugin sowohl Objective-C als auch Swift verwendet, müssen Sie diese in separate Targets aufteilen:

targets: [
    // Reine Objective-C-Target
    .target(
        name: "my_plugin_objc",
        path: "Sources/my_plugin_objc",
        publicHeadersPath: "include"
    ),
    // Swift-Target hängt vom Obj-C-Target ab
    .target(
        name: "my_plugin",
        dependencies: ["my_plugin_objc"],
        path: "Sources/my_plugin"
    )
]

Quellcodedateien umstrukturieren

# Quellverzeichnis für SwiftPM erstellen
mkdir -p ios/my_plugin/Sources/my_plugin

# Bestehende Quellen kopieren (für CocoaPods beibehalten)
cp ios/Classes/MyPlugin.swift ios/my_plugin/Sources/my_plugin/
cp ios/Classes/MyPlugin.m ios/my_plugin/Sources/my_plugin/  # Falls Obj-C vorhanden ist

Flutter Framework-Abhängigkeit hinzufügen

Wenn Sie native Flutter-APIs nutzen (z. B. FlutterPlugin-Protokoll, FlutterMethodChannel), müssen Sie das Flutter Framework als Abhängigkeit angeben:

// ios/my_plugin/Package.swift
let package = Package(
    name: "my_plugin",
    platforms: [.iOS(.v13)],
    products: [
        .library(name: "my-plugin", targets: ["my_plugin"])
    ],
    dependencies: [
        // Flutter-Framework-Abhängigkeit hinzufügen (erforderlich!)
        .package(
            url: "https://github.com/nicehash/flutter",
            from: "1.0.0"
        )
    ],
    targets: [
        .target(
            name: "my_plugin",
            dependencies: [
                .product(name: "Flutter", package: "flutter")
            ],
            path: "Sources/my_plugin"
        )
    ]
)

Hinweis: Verwenden Sie für die offizielle Package.swift-URL die vom Flutter-Team bereitgestellte URL. Da die Flutter-CLI bei der Ausführung automatisch das richtige Framework bereitstellt, wird der Pfad aus dem Flutter-SDK in der Praxis automatisch injiziert.

pubspec.yaml aktualisieren

# pubspec.yaml (Plugin)
name: my_plugin
version: 2.0.0

flutter:
  plugin:
    platforms:
      ios:
        # CocoaPods-Konfiguration (Abwärtskompatibilität)
        podspec: ios/my_plugin.podspec
        # SwiftPM-Konfiguration hinzufügen
        swiftPackage: ios/my_plugin

Überprüfung mit der Beispiel-App

# SwiftPM-Migration in der Beispiel-App des Plugins aktivieren
cd example

flutter config --enable-swift-package-manager
flutter run -d iPhone  # Echtes Gerät oder Simulator

# In Xcode überprüfen
open ios/Runner.xcworkspace
# Erfolgreich, wenn my_plugin in Package Dependencies erscheint

CI-Pipeline aktualisieren

# .github/workflows/test.yml
- name: Flutter iOS Build (SwiftPM)
  run: |
    flutter config --enable-swift-package-manager
    flutter build ios --no-codesign --simulator
  env:
    FLUTTER_VERSION: "3.44.0"

# Bestehenden CocoaPods-Build parallel testen (Abwärtskompatibilität prüfen)
- name: Flutter iOS Build (CocoaPods fallback)
  run: |
    flutter config --no-enable-swift-package-manager
    flutter build ios --no-codesign --simulator

Migrations-Zeitplan und Risikoanalyse

Was Sie jetzt tun sollten:

• App-Entwickler: Führen Sie flutter config --enable-swift-package-manager aus und testen Sie den Build.
• Plugin-Autoren: Fügen Sie Package.swift hinzu und veröffentlichen Sie eine neue Version auf pub.dev.

Bis Dezember 2026 zwingend abzuschließen:

• SwiftPM-Unterstützung aller verwendeten Plugins überprüfen.
• Alternativen für nicht unterstützte Plugins suchen oder selbst PRs beisteuern.

Fehlerbehebung: Häufige Probleme

Fehler 1: “Sources folder not found”

error: Source files for target 'my_plugin' should be located under 'Sources/my_plugin'

Ursache: SwiftPM setzt voraus, dass sich Quelldateien unter Sources/<Target-Name>/ innerhalb des Paketroots befinden.
Lösung: Verschieben Sie die Quelldateien nach ios/my_plugin/Sources/my_plugin/.

Fehler 2: “Cannot use Swift and Objective-C in the same target”

Ursache: SwiftPM erlaubt keine unterschiedlichen Sprachen im selben Target.
Lösung: Trennen Sie den Code in ein reines Obj-C-Target und ein Swift-Target.

Fehler 3: Nach pod install wird weiterhin nur CocoaPods verwendet

# Erzwungenen SwiftPM-Modus prüfen
flutter config | grep swift-package-manager

# Falls nicht aktiviert:
flutter config --enable-swift-package-manager
flutter clean && flutter pub get

Fehler 4: “FlutterGeneratedPluginSwiftPackage not found”

# Xcode-Cache bereinigen
rm -rf ~/Library/Developer/Xcode/DerivedData
cd ios && xcodebuild -resolvePackageDependencies

Fehler 5: Warnungen bezüglich Bitcode

SwiftPM deaktiviert Bitcode standardmäßig. Da Apple Bitcode seit iOS 16 als veraltet (deprecated) eingestuft hat, können Sie diese Warnung ignorieren.

Auswirkungen auf den pub.dev-Score

pub.dev berücksichtigt die SwiftPM-Unterstützung seit 2025 bei der Berechnung des Plugin-Scores. Die Bewertungskategorien sehen wie folgt aus:

Der pub.dev-Score (maximal 100 Punkte) beeinflusst das Suchranking direkt. Die SwiftPM-Unterstützung ist somit kein optionales Feature mehr, sondern Pflicht.

Fazit

Das Ende von CocoaPods ist eine der bedeutendsten Veränderungen im Flutter-iOS-Ökosystem. Der Umstieg auf den Swift Package Manager ist kein bloßer Werkzeugwechsel, sondern die Rückkehr in das offizielle Apple-Ökosystem.

Die gute Nachricht für App-Entwickler: In den meisten Fällen erfolgt die automatische Migration mit einem einzigen Aufruf von flutter run. Probleme entstehen hauptsächlich dann, wenn Sie von Plugins abhängen, die SwiftPM noch nicht unterstützen.

Wenn Sie ein Plugin-Autor sind, sollten Sie noch heute Package.swift hinzufügen. Nach Dezember 2026 wird das Veröffentlichen neuer Versionen auf CocoaPods unmöglich sein.

Aktionsplan:

1. flutter config --enable-swift-package-manager ausführen
2. Build mit flutter run testen
3. Liste gewarnter Plugins prüfen und Lösungsstrategie festlegen
4. (Für Plugin-Autoren) Package.swift hinzufügen und neues Release auf pub.dev veröffentlichen

Verwandter Artikel: Werfen Sie auch einen Blick auf den Leitfaden zur Android-Optimierung in 16-KB-Seitengröße: Warum Google Play dich ablehnt.