Swift 6.4 duplicate module name: 2026 Remote-Mac-CI beheben

Swift 6.4 duplicate module name beheben Sie zunächst durch die Suche nach zwei erreichbaren Clang-Moduldeklarationen, nicht durch einen vollständigen Node-Neuaufbau oder ein blindes Rollback. Das gilt, wenn der stabile Build weiterhin funktioniert, der Swift-6.4-Knoten aber beim Dependency-Scan erstmals scheitert: Sichern Sie zuerst Log, Toolchain, Suchpfade und Lock-Datei, isolieren Sie danach module.modulemap und entscheiden Sie erst am Ende über Reparatur oder Doppelbetrieb.

Dieser Leitfaden richtet sich an Sie, wenn Sie Swift-Projekte mit Objective-C-, C/C++- oder binären SDK-Abhängigkeiten warten und nach dem Upgrade erstmals einen Modulnamenskonflikt sehen. Ebenso relevant ist er für DevOps- und Build-Teams, die Remote-Mac-CI-Knoten, Caches und mehrere Xcode-Versionen verwalten. Plattformverantwortliche erhalten eine belastbare Grundlage für die Entscheidung zwischen Abhängigkeitsreparatur, Aufschub und zwei parallelen Toolchains.

Zuletzt aktualisiert: 08.09.2026. Der Versionsstand wurde gegen die Xcode-27-Release-Notes und die offiziellen Xcode-Systemanforderungen geprüft. Xcode 27 beta 6 wird dort mit Swift 6.4 geführt; daraus darf keine Aussage über eine unveränderte Regel in einer späteren finalen Ausgabe abgeleitet werden.

SECTION 01 Zeitplan und Beweisgrenze

Behandeln Sie den Fehler zunächst als Beweisproblem. Der erste gültige Compiler- oder Dependency-Scanner-Hinweis ist wichtiger als der abschließende Exit-Code. Ein Build kann mit „module not found“, einer Definitionserneuerung, einem Linkerfehler oder einem doppelten Modulnamen enden; diese Klassen verlangen unterschiedliche Maßnahmen.

Markieren Sie in der fehlgeschlagenen Pipeline mindestens folgende Daten:

den aktiven Xcode- und Swift-Pfad für den fehlgeschlagenen Schritt;
die vollständige Buildzeile einschließlich Header Search Paths und zusätzlicher Compilerflags;
den exakten Fehlertext samt vorhergehender Diagnose;
den Commit, Package.resolved beziehungsweise die verwendete Abhängigkeitsrevision;
den Zustand von DerivedData, Module Cache und eigenen Abhängigkeits-Caches.

Vergleichen Sie anschließend denselben Commit mit der stabilen Toolchain. Wenn dort ein Linkerfehler auftritt, während Swift 6.4 bereits beim Auffinden oder Laden eines Clang-Moduls stoppt, handelt es sich nicht um dieselbe Fehlerklasse. Die Apple-Dokumentation zu Build-Settings hilft dabei, die tatsächlich wirksamen Ziel- und Suchpfade von scheinbar ähnlichen Xcode-Konfigurationen zu unterscheiden.

Die offizielle Xcode-27-Dokumentation bestätigt die verschärfte Eindeutigkeitsanforderung für erreichbare Clang-Modulnamen innerhalb eines Dependency-Scans. Das erklärt, weshalb eine alte Toolchain einen problematischen Zustand verdecken kann. Es beweist jedoch nicht, welches Paket in Ihrem Projekt verantwortlich ist. Die konkrete Ursache muss aus Ihrem Log, den geladenen Pfaden oder einer reproduzierbaren lokalen beziehungsweise Remote-Mac-Ausführung kommen.

SECTION 02 Quellen des Modulkonflikts

Eigene Module Map und Bridging Header

Prüfen Sie zuerst, ob Ihr Repository ein eigenes module.modulemap enthält und ob dasselbe Modul zusätzlich durch eine vendored Bibliothek oder ein SDK bereitgestellt wird. Entscheidend sind nicht nur identische Dateinamen, sondern der deklarierte Modulname, die Header-Einstiegspunkte und der Pfad, unter dem der Compiler die Datei erreicht.

Ein häufiger Fehler entsteht, wenn ein eigenes C- oder Objective-C-Modul denselben Namen wie eine eingebundene Komponente erhält. Ein Bridging Header kann dabei eine weitere Sicht auf dieselben Header erzeugen, ohne selbst eine Module Map zu sein. Entfernen Sie deshalb nicht wahllos Verzeichnisse aus dem Repository. Ordnen Sie jeder Deklaration einen Besitzer zu und entscheiden Sie dann zwischen diesen Reparaturen:

eine doppelte Deklaration in eine einzige gepflegte Module Map zusammenführen;
ein eigenes Modul eindeutig umbenennen und alle Swift-Imports anpassen;
einen überflüssigen Header Search Path aus dem Ziel entfernen;
die Dependency-Version aktualisieren, wenn der Maintainer bereits eine kompatible Korrektur anbietet.

Die SwiftPM-Dokumentation zu Systembibliotheksabhängigkeiten beschreibt, wie eine Systembibliothek über eine Module Map angebunden wird. Diese Beschreibung ist keine Diagnose Ihres Projekts, liefert aber den richtigen Prüfrahmen für Paketmanifest, Modulnamen und Header-Verzeichnis.

Drittanbieter-SDK und Systemmodul

Die zweite Fehlerquelle liegt außerhalb Ihres Quellcodes. Kontrollieren Sie vendored Sources, XCFrameworks, Swift Packages und manuell eingebundene SDKs darauf, ob sie jeweils eine Module Map oder einen Modulordner mitbringen. Trennen Sie zwei Fälle:

Zwei Drittanbieter-Komponenten erklären denselben eigenen Modulnamen.
Ein Drittanbieter erklärt einen Namen, der bereits durch ein System- oder SDK-Modul erreichbar ist.

Im ersten Fall benötigen Sie eine eindeutige Abhängigkeitsauswahl oder eine gepflegte Aktualisierung. Im zweiten Fall sollten Sie nicht versuchen, das Systemmodul durch einen beliebigen Suchpfad auszublenden. Ein binäres SDK ohne Quellcode muss in einer isolierten Spur geprüft werden; ein unmaintained Patch gehört nicht dauerhaft in die Produktionspipeline, solange weder Herkunft noch Nebenwirkungen dokumentiert sind.

Die Swift-Clang-Dokumentation zu Modulen und die Clang-Referenz zu Modules sind für diese Unterscheidung maßgeblich. Sie erklären Moduldeklarationen und deren Auflösung, ersetzen aber nicht die Prüfung der konkreten SDK-Version. Community-Issues können einen Suchhinweis liefern; behandeln Sie sie nur als Einzelfall und gleichen Sie Toolchain, Plattform und Abhängigkeitsstand ab.

Remote-Mac-Suchpfad

Ein Remote-Mac-CI-Knoten kann einen lokal unsichtbaren Konflikt sichtbar machen, weil dort zusätzliche Homebrew-, SDK- oder Workspace-Pfade in die Buildumgebung gelangen. Vergleichen Sie nicht nur Xcode-Versionen, sondern auch:

PATH, SDKROOT, DEVELOPER_DIR und projektspezifische Variablen;
Shell-Initialisierung des CI-Benutzers gegenüber Ihrer interaktiven Sitzung;
Arbeitsverzeichnis und generierte Build-Skripte;
zusätzliche -I, -F oder -isystem-Argumente;
den Inhalt von Package.resolved und die tatsächlich ausgecheckten Revisionen.

Verwenden Sie die Compiler- beziehungsweise Modul-Ladeprotokolle, um festzustellen, welche module.modulemap wirklich gelesen wird. Eine globale Suche nach gleichnamigen Dateien ist nur ein Anfang: Ein nicht erreichbarer Fund ist kein aktiver Konflikt, während ein generierter oder über einen zusätzlichen Suchpfad zugänglicher Pfad sehr wohl relevant sein kann.

Beachten Sie außerdem Benutzer- und Sitzungsgrenzen. Ein interaktiver SSH-Test kann eine andere Shell-Konfiguration, ein anderes Home-Verzeichnis oder andere Berechtigungen verwenden als der CI-Agent. Dokumentieren Sie daher den effektiven Benutzer, das Arbeitsverzeichnis und die vollständige Buildzeile. Für langfristig reproduzierbare Remote-Mac-CI sollten Sie den Knoten als versionierte Buildumgebung behandeln, nicht als identische Verlängerung Ihres Entwicklerlaptops.

SECTION 03 Cache-Zustand und Kaltstart

DerivedData und Module Cache können zwei gegensätzliche Effekte haben: Ein alter Zwischenstand lässt den Fehler weiter erscheinen, oder ein günstiger Cache verschleiert, dass ein sauberer Build weiterhin scheitern würde. Deshalb ist „Cache löschen“ keine Primärreparatur.

Arbeiten Sie in dieser Reihenfolge:

Erstellen Sie ein neues Arbeitsverzeichnis mit demselben Commit und derselben Lock-Datei.
Setzen Sie einen unabhängigen DerivedData-Pfad für genau diesen Versuch.
Verwenden Sie einen separaten Module-Cache-Pfad, soweit Ihre Buildparameter das erlauben.
Protokollieren Sie die Cache-Orte, bevor Sie sie entfernen.
Wiederholen Sie den Build ohne globale Node-Bereinigung.
Führen Sie nach der Ursachenreparatur sowohl einen kalten als auch einen inkrementellen Build aus.

Eine begrenzte Cache-Bereinigung darf parallele Jobs nicht unbemerkt beschädigen. Löschen Sie keine gemeinsam genutzten Verzeichnisse, während andere Pipelines sie verwenden, und halten Sie den alten Pfad für eine Wiederherstellung oder forensische Prüfung fest. Wenn ein isolierter Kaltstart weiterhin dieselben zwei Modulquellen meldet, ist der Cache als Hauptursache ausgeschlossen.

SECTION 04 Entscheidungs-Checkliste für die nächste Pipeline

Verwenden Sie diese Checkliste als Freigabepunkt, bevor Sie die Toolchain oder die Abhängigkeiten im Produktionszweig ändern:

[ ] Der erste gültige Fehler ist dokumentiert und als duplicate module, module not found, Definitionserneuerung oder Linkerfehler klassifiziert.
[ ] Aktiver Xcode-Pfad, Swift-Version, Commit, Package.resolved und vollständige Buildparameter sind aus demselben Lauf gesichert.
[ ] Für jede erreichbare Deklaration des betroffenen Clang-Moduls ist ein Besitzer bekannt.
[ ] Die tatsächlich geladene module.modulemap wurde über Modul- oder Compilerdiagnose bestätigt; eine reine globale Dateisuche genügt nicht.
[ ] Zusätzliche Header-, Framework- und SDK-Suchpfade des Remote-Mac-CI-Knotens wurden mit dem lokalen Lauf verglichen.
[ ] Der Fehler wurde in einem neuen Arbeitsverzeichnis mit getrenntem DerivedData- und Module-Cache-Pfad erneut geprüft.
[ ] Eine Reparatur verändert nur die zuständige Module Map, einen belegten Suchpfad oder eine gepflegte Dependency-Version.
[ ] Nach der Änderung bestehen sowohl Kaltbuild als auch Inkrementalbuild.
[ ] Derselbe Build wurde wiederholt, ohne dass ein manuelles Löschen gemeinsamer Caches erforderlich war.
[ ] Für ein nicht änderbares binäres SDK ist die Produktionsspur weiterhin auf der stabilen Toolchain belassen worden.

Treffen Sie danach die Entscheidung anhand dieser Bedingungen:

Wenn alle relevanten Modulquellen eindeutig sind, der Kaltbuild erfolgreich ist und wiederholte Builds ohne Cache-Sonderbehandlung bestehen, dann können Sie Swift 6.4 zunächst für eine begrenzte Produktionsgruppe freigeben.
Wenn Ihr eigenes Modul denselben Namen wie eine Abhängigkeit verwendet, dann benennen Sie Ihr Modul kontrolliert um oder führen Sie die Deklarationen zusammen; löschen Sie nicht nur einen zufällig gefundenen Ordner.
Wenn zwei Drittanbieter-Abhängigkeiten denselben Namen liefern, dann wählen Sie eine kompatible Version oder isolieren Sie den betroffenen Anbieter, bevor Sie den Produktionsbuild ändern.
Wenn ein binäres SDK den Konflikt verursacht und kurzfristig nicht aktualisiert werden kann, dann bleibt die stabile Toolchain die Produktionsspur; Swift 6.4 läuft zunächst als getrennte Kompatibilitätsspur.
Wenn der Fehler nur nach einer Cache-Löschung verschwindet, dann behandeln Sie das als Cache- oder Nebenläufigkeitsproblem und nicht als bewiesene SDK-Kompatibilität.
Wenn die Ursache weder reproduzierbar noch einer Modulquelle zugeordnet werden kann, dann stoppen Sie die Umstellung und sammeln Sie weitere Logs, statt den gesamten Node neu aufzubauen.

SECTION 05 Doppelbetrieb und Rückfall

Für die Doppelspur sollten Sie einen unveränderlichen Vergleich definieren: gleicher Commit, gleiche Paketauflösung, gleicher Signierungs- und Buildauftrag, getrennte Ausgabe- und Cache-Pfade. Die stabile Spur schützt die Produktion; die Swift-6.4-Spur liefert den Nachweis, ob eine Abhängigkeit später gefahrlos aktualisiert werden kann.

Ein Rückfall ist angemessen, wenn der Fehler durch ein nicht kontrollierbares SDK ausgelöst wird, keine kompatible Version existiert und der Produktionszweig kurzfristig weiterliefern muss. Lassen Sie den Swift-6.4-Knoten trotzdem aktiv, sofern er isoliert ist und reproduzierbare Diagnoseprotokolle erzeugt. So verlieren Sie den Upgrade-Fortschritt nicht und vermeiden zugleich einen ungeprüften Eingriff in die Releasepipeline.

Ein vollständiger Node-Neuaufbau ist erst dann sinnvoll, wenn Sie einen beschädigten oder nicht reproduzierbaren Maschinenzustand nachweisen können. Er ist kein Ersatz für die Zuordnung der beiden Moduldeklarationen. Andernfalls kann der Konflikt nach der Neuinstallation mit denselben Abhängigkeiten und Suchpfaden unverändert zurückkehren.

SECTION 06 FAQ zur Swift-6.4-Diagnose

Warum funktioniert der alte Build noch?

Der alte Dependency-Scanner kann eine problematische Kombination aus Suchpfaden oder Moduldeklarationen anders behandeln und den Konflikt dadurch nicht sichtbar machen. Die Xcode-27-Release-Notes nennen für die neue Scanner-Logik die Eindeutigkeit erreichbarer Clang-Modulnamen. Das ist ein plausibler Auslöser, aber kein Beweis für jede Drittanbieterbibliothek. Entscheidend bleiben Ihr erster gültiger Fehler, die aktive Toolchain und die geladenen Modulpfade.

Wie ordnen Sie zwei Module-Maps ihren Abhängigkeiten zu?

Erfassen Sie zunächst die vollständige Compilerzeile und die tatsächlich gesetzten Include- und Framework-Pfade. Suchen Sie anschließend innerhalb dieser Pfade nach module.modulemap und vergleichen Sie Modulname, Header-Einstieg und Paketbesitzer. Ergänzen Sie die Prüfung durch Modul-Ladeprotokolle. Damit unterscheiden Sie eine nur vorhandene Datei von einer Deklaration, die der konkrete Swift- oder Clang-Aufruf tatsächlich erreichen kann.

Wann reicht DerivedData-Löschen aus?

Es reicht nur dann, wenn ein isolierter Kaltstart den Konflikt nicht mehr reproduziert und ein anschließender Wiederholungsbuild stabil bleibt. Sobald zwei Module Maps im gleichen Scan erreichbar sind, ändert das Entfernen von DerivedData nichts an der Ursache. Begrenzen Sie die Bereinigung auf den betroffenen Build und dokumentieren Sie Auswirkungen auf parallele Jobs. Eine globale Cache-Löschung ist weder der erste noch der sicherste Schritt.

Welche CI-Strategie gilt bei einem nicht änderbaren SDK?

Lassen Sie die stabile Toolchain in der Produktionsspur und reservieren Sie eine getrennte Swift-6.4-Spur für denselben Commit und dieselbe Abhängigkeitsauflösung. Prüfen Sie dort Kalt- und Inkrementalbuild sowie wiederholte Ausführung. Erst wenn das SDK aktualisiert oder die Modulquelle eindeutig isoliert wurde, sollte die neue Toolchain produktive Jobs übernehmen. So bleibt die Kompatibilitätsarbeit sichtbar, ohne den Releasepfad mit einem unkontrollierten Patch zu belasten.

SECTION 07 Meilensteine für die Freigabe

Planen Sie die Arbeit nicht als einmaliges „Upgrade erfolgreich“, sondern als Folge überprüfbarer Meilensteine:

Diagnose abgeschlossen: Fehlerklasse, Toolchain, Commit und aktive Suchpfade sind im Log festgehalten.
Quelle zugeordnet: Jede erreichbare Deklaration des betroffenen Clang-Moduls hat einen bekannten Besitzer.
Reparatur begrenzt: Die Änderung betrifft nur Modulquelle, Suchpfad oder eine gepflegte Dependency-Version; kein zufälliges Löschen.
Kaltstart bestanden: Neuer DerivedData- und Module-Cache-Pfad reproduziert den Fehler nicht mehr.
Wiederholbarkeit bestätigt: Mehrere identische Builds liefern denselben Erfolg ohne manuelle Eingriffe.
Produktionsentscheidung getroffen: Freigabe, Doppelspur oder Rückfall ist anhand der oben genannten Bedingungen dokumentiert.

Wenn Sie für diese Tests eine getrennte, jederzeit neu aufsetzbare macOS-Umgebung benötigen, kann ein gemieteter Remote Mac die Untersuchung gegenüber einem gemeinsam genutzten Entwicklergerät vereinfachen. Sie erhalten dabei eine echte Mac-Umgebung mit Root-Zugriff, müssen aber Netzwerkzugriff, Geheimnisse, SSH- beziehungsweise VNC-Berechtigungen und DSGVO-Anforderungen selbst sauber begrenzen. Für einen dauerhaft schweren, stabilen Produktionsdurchsatz kann der Kauf eigener Hardware wirtschaftlicher sein; für zeitlich begrenzte Toolchain-Validierung ist die Mietlösung flexibler.

Gegenüber einer lokalen Mac-mini-Installation entstehen bei der aktuellen Lösung drei typische Nachteile: Sie sind von Netzwerkqualität und Remote-Zugriff abhängig, müssen Cache- und Identitätsgrenzen auf einem gemeinsam verwalteten Knoten sorgfältiger planen und haben weniger Kontrolle über physische Schnittstellen. Wenn Ihre Aufgabe jedoch lautet, stabile CI weiterlaufen zu lassen und Swift 6.4 in einer isolierten Spur mit realem macOS zu prüfen, kann VPSNIX die passendere Zwischenstufe sein als ein vorschneller Hardwarekauf. Informationen zu verfügbaren Mietoptionen finden Sie auf der VPSNIX-Übersicht für Mac-Umgebungen.