Xcode JSON xcproj: Das neue Projektformat in Xcode 27.2

Jedes Xcode-Projekt hat eine Datei, die fast niemand freiwillig liest: project.pbxproj. Aus ihr stammen die Merge-Konflikte, wenn zwei Personen auf verschiedenen Branches Dateien hinzufügen. Xcode 27.2 ersetzt sie. Das Format Xcode JSON xcproj, eine Datei namens project.xcproj, speichert dieselbe Projektkonfiguration als hierarchisches JSON, mit dem Menschen, Diff-Tools und Coding-Agents tatsächlich arbeiten können.

Dieser Leitfaden erklärt, was die neue Datei ist, warum Apple sie geändert hat, wie sie aussieht, wie Sie ein Projekt umstellen und was Sie vor dem Wechsel prüfen sollten: ältere Xcode-Versionen, CI und Tools von Drittanbietern. Er basiert auf Apples Dokumentation und Release Notes, Apples Open-Source-Package für das Format sowie Artikeln von @sarunw und Artem Novichkov. Das Format ist neu in Xcode 27.2, und Details können sich zwischen Releases ändern.

Was ist das neue JSON-Format .xcproj in Xcode 27.2?

Ein .xcodeproj ist ein Ordner. Darin liegt die Datei für die Projektkonfiguration, zusammen mit anderen Dateien wie geteilten Schemes. Apples Artikel Updating your Xcode project configuration file format erklärt die Änderung: In früheren Releases ist diese Datei eine Property List mit der Endung .pbxproj, und in Xcode 27.2 und neuer ist der Standard eine kleinere, hierarchische, selbstbeschreibende JSON-Datei mit der Endung .xcproj.

Drei Fakten bilden den Rahmen für alles Weitere:

• Neue Projekte erhalten standardmäßig JSON. Projekte, die Sie in Xcode 27.2 und neuer erstellen, verwenden project.xcproj.
• Bestehende Projekte ändern sich nicht von selbst. Xcode 27 und neuer unterstützt beide Formate, und Sie entscheiden, wann Sie wechseln.
• Das Format ist Open Source. Apple veröffentlicht es als xcode-project-format, ein Swift Package, das die Datei als typisierte Werte modelliert.

Die Release Notes zu Xcode 27.2 fassen es in einem Satz zusammen: Das JSON-basierte Format ist lesbarer, mergefreundlicher und für Coding-Agents leichter zu bearbeiten. Wie @sarunw es zum Erscheinen von 27.2 formulierte: Xcode 27.2 ersetzt .pbxproj durch ein neues JSON-Format .xcproj.

Warum ersetzt Apple project.pbxproj?

Das alte Format speichert das Projekt als flache Liste von Objekten, die jeweils über eine undurchsichtige, 24-stellige hexadezimale ID adressiert werden. Objekte verweisen über diese IDs aufeinander. Eine Swift-Datei zu einem Target hinzuzufügen, berührt typischerweise mehrere Abschnitte gleichzeitig: eine Dateireferenz, ihren Platz in einer Gruppe, einen Build-File-Eintrag und die Build Phase Sources des Targets. @sarunw beschreibt das bekannte Ergebnis als eine Änderung, die über drei Abschnitte von project.pbxproj neu geschrieben wird. Wenn zwei Branches je eine Datei hinzufügen, kollidieren diese verstreuten Änderungen, und sie von Hand aufzulösen bedeutet, IDs über Abschnitte hinweg abzugleichen.

Build Settings hatten ein ähnliches Problem. Jede Konfiguration, etwa Debug und Release, hatte einen eigenen vollständigen Block an Einstellungen, sodass eine Einstellung an mehreren Stellen mit unterschiedlichen Werten auftauchen konnte.

Apples Dokumentation nennt drei Gründe für das neue Format:

1. Nachvollziehbare Diffs. Änderungen in der Vergleichsansicht entsprechen Ihren Aktionen in Xcode.
2. Weniger Merge-Konflikte. Das JSON-Format isoliert Konfigurationsänderungen, sodass voneinander unabhängige Änderungen seltener dieselben Zeilen berühren.
3. Agent-freundlich. Coding-Agents können die Datei leichter für Sie bearbeiten.

Die synchronisierten Ordner aus Xcode 16 haben bereits Einträge pro Datei für Dateien in diesen Ordnern entfernt. Der Artikel von @sarunw merkt an, dass das JSON-Format weiter geht, weil Targets, Build Phases, Konfigurationen und Package-Referenzen in der Property List weiterhin IDs verwendeten.

Wie sieht eine project.xcproj-Datei aus?

Apple veröffentlicht in seiner Dokumentation keine vollständige Beispieldatei, aber das Open-Source-Package definiert die Schlüssel der obersten Ebene. Dazu gehören default-configuration, configurations, localizations, files, targets, packages und build-settings. Hier ein gekürzter Auszug mit diesen Schlüsseln und Werten aus dem Demoprojekt von @sarunw. Es ist keine vollständige Datei.

{
  "default-configuration": "Debug",
  "build-settings": {
    "DEBUG_INFORMATION_FORMAT[config=Debug]": "dwarf",
    "DEBUG_INFORMATION_FORMAT[config=Release]": "dwarf-with-dsym"
  }
}

Eine Build Setting wird einmal geschrieben. Brauchen Konfigurationen unterschiedliche Werte, steht die Bedingung im Schlüssel, wie oben bei [config=Debug]. Dateien sind Einträge im Baum files, und jede trägt ihre eigene Target-Zugehörigkeit, statt aus einer separaten Build-Phase-Liste referenziert zu werden. Im Beispiel von @sarunw ist eine Datei eine einzige Zeile:

{ "path": "CatalogView.swift", "target-membership": [ "ToolbarPlacements/compile-sources" ] }

Der Größenunterschied ist spürbar. Im Demoprojekt von @sarunw wurde aus einer Property List mit 300 Zeilen JSON mit 123 Zeilen. Artem Novichkovs Vergleich ergab, dass dasselbe Swift Package in project.pbxproj 24 Zeilen an fünf Stellen brauchte und in project.xcproj 12 Zeilen an zwei Stellen. Die Ergebnisse variieren je nach Projekt, aber die Richtung ist eindeutig.

Wie stelle ich ein Xcode-Projekt auf JSON xcproj um?

Committen Sie zuerst Ihre Arbeit, damit die Umstellung eine saubere, separate Änderung ist. Dann in Xcode 27.2:

1. Wählen Sie das Projekt oben im Project Navigator aus.
2. Öffnen Sie den File Inspector.
3. Wählen Sie unter Project Document im Pop-up-Menü Project Format den Eintrag JSON.
4. Wenn ein Dialog erscheint, klicken Sie auf Continue.

Im Ordner .xcodeproj wird project.pbxproj entfernt und project.xcproj hinzugefügt. Apple merkt an, dass Sie den Wechsel bei Verwendung einer Versionskontrolle rückgängig machen können, indem Sie diese beiden Dateiänderungen verwerfen. Schemes und andere Dateien im Bundle sind nicht Teil der Änderung.

Für Skripte und große Repositories berichtet Artem Novichkov, dass xcodebuild in Xcode 27.2 in beide Richtungen umwandeln kann. Er stellte außerdem fest, dass die umgewandelte Datei das Original ersetzt, ein weiterer Grund, zuerst zu committen. Prüfen Sie xcodebuild -help auf Ihrem Rechner, da dies nicht in Apples Artikel steht.

xcodebuild -project Weather.xcodeproj -convert-project xcproj
xcodebuild -project Weather.xcodeproj -convert-project pbxproj

Welche Xcode-Versionen und Tools können .xcproj lesen?

Laut Apples Dokumentation ist das Format .xcproj mit Xcode 27 und neuer kompatibel, und die Release Notes sagen, dass Projekte in diesem Format auch in früheren Versionen von Xcode 27 öffnen. Ein Team mit Xcode 27.0 oder 27.1 kann ein umgestelltes Projekt also öffnen, die Umstellungsoption selbst gibt es aber erst in 27.2. Wer Xcode 26 oder älter nutzt, braucht das Property-List-Format, das laut dem Artikel von @sarunw die Wahl für ältere Xcode-Versionen bleibt.

Die Unterstützung durch Drittanbieter kommt erst nach und nach. Die Bibliothek XcodeProj von Tuist, auf der viele Tools aufbauen, hat in Release 9.17.0 „[Experimental] support Xcode 27.2's JSON project format (project.xcproj)“ ergänzt. Unterstützung in XcodeGen oder im xcodeproj-Gem von CocoaPods konnten wir nicht bestätigen, behandeln Sie also jedes Tool, das project.pbxproj bearbeitet, als nicht unterstützt, bis dessen eigene Release Notes etwas anderes sagen. Wenn Sie Ihr Projekt aus einer Spezifikation generieren und nicht committen, spielt das Format eine geringere Rolle, solange der Generator weiter funktioniert.

Für eigene Tools ist Apples Package der bessere Weg. Es erfordert Swift 6.1 oder neuer, baut auf macOS 14 und neuer sowie auf anderen Plattformen und steht unter der Lizenz Apache 2.0 mit Runtime Library Exception. Die README zeigt, wie man ein Projekt mit XCSchema.Project liest:

import XcodeProjectFormat

func listTargets(in projectURL: URL) throws {
    let projectData = try Data(contentsOf: projectURL)
    let project = try XCSchema.Project(jsonRepresentation: projectData)
    for target in project.targets {
        print(target.name)
    }
}

Wie hilft xcproj Coding-Agents und CI?

@sarunw fasst die Änderung so zusammen, dass das JSON-Format für Menschen besser lesbar und für Coding-Agents bearbeitbar ist, was Apples eigener Formulierung entspricht. Ein Agent, der einer Property List eine Datei oder ein Package hinzufügt, muss gültige IDs erfinden und jeden Abschnitt aktualisieren, der darauf verweist. Mit JSON ist die Änderung klein und lokal, und Sie können sie in einem Pull Request prüfen.

Apples Package liefert außerdem xcprojformatter mit, ein Kommandozeilen-Tool auf Basis der Bibliothek. Artem Novichkov beschreibt, wie er es mit xcrun xcprojformatter ausführt: Es gibt die Datei in kanonischer Form aus, und --update schreibt sie direkt um. Das ergibt eine nützliche CI-Prüfung, weil ein Diff des Formatters jede manuelle oder von einem Agent stammende Änderung zeigt, die nicht in kanonischer Form vorliegt. Prüfen Sie xcrun xcprojformatter --help auf die genauen Argumente, die Ihre Version akzeptiert.

xcrun xcprojformatter --update MyApp.xcodeproj/project.xcproj
git diff --exit-code -- MyApp.xcodeproj/project.xcproj

Er stellte außerdem fest, dass der Formatter unbekannte Schlüssel stillschweigend entfernt, etwa einen falsch geschriebenen, prüfen Sie also, was er ändert, statt anzunehmen, dass er alles validiert. Dasselbe gilt nach einem Merge-Konflikt: Lösen Sie das JSON auf, führen Sie den Formatter aus und prüfen Sie, ob Targets und Packages in Xcode noch richtig aussehen.

Spielt das JSON-Projektformat für iPhone-Duo-Apps eine Rolle?

Nicht dafür, wie Ihre App läuft. Das Projektformat ändert nur, wie Xcode Ihre Konfiguration speichert; die App, die Sie für iPhone oder iPhone Duo bauen, ist dieselbe. Für die Arbeit drumherum spielt es aber eine Rolle. Eine App für das iPhone Duo anzupassen bedeutet, mit dem iOS 27.1 SDK neu zu bauen und oft Projekteinstellungen über mehrere Branches hinweg anzufassen, und genau dann tauchen Merge-Konflikte in project.pbxproj auf.

Es passt außerdem gut zu den eingebauten Agent Skills von Xcode 27, die aktuelle Best Practices und neue APIs abdecken. Wie @sarunw anmerkt, heißt der frühere Skill uikit-app-modernization jetzt app-resizability und unterstützt das iPhone Duo. Wenn Sie sich bei dieser Arbeit von einem Agent helfen lassen, hält eine JSON-Projektdatei seine Änderungen klein genug für ein Review. Unser Leitfaden zum Export der Agent Skills von Xcode 27 behandelt diese Seite, und die Checkliste zur iPhone Duo Vorbereitung listet die Änderungen an der App selbst auf.

Die wichtigsten Punkte

• Xcode 27.2 ersetzt project.pbxproj für neue Projekte standardmäßig durch project.xcproj, eine kleinere, hierarchische JSON-Datei.
• Mit dem JSON-Format entsprechen Diffs Ihren Aktionen, Änderungen werden isoliert, was Merge-Konflikte reduziert, und Coding-Agents können die Datei leichter bearbeiten.
• Stellen Sie bestehende Projekte im File Inspector unter Project Document um; committen Sie vorher, damit Sie es rückgängig machen können.
• .xcproj öffnet in Xcode 27 und neuer. Behalten Sie die Property List, wenn jemand oder ein CI-Rechner noch Xcode 26 nutzt.
• Prüfen Sie vor dem Wechsel Generatoren, Skripte und Dependency Manager, die project.pbxproj parsen; Apples Open-Source-Package und xcprojformatter helfen bei eigenen Tools.

Wenn Ihr Projekt in Ordnung ist, bringen Sie es aufs Gerät: Beginnen Sie mit der Checkliste zur iPhone Duo Vorbereitung, und sehen Sie unter Built for the fold, was andere Entwickler bereits veröffentlicht haben.