Zum Hauptinhalt springen
Die lokale App-Entwicklung dreht sich um Syncing: Die CLI baut Ihr Manifest neu auf und der Server wendet nur die Differenz zwischen diesem und den Metadaten an, die sich bereits in Ihrem Workspace befinden. Diese Seite behandelt, zu welchem Befehl Sie greifen sollten, wie Sie lesen, was ein Sync geändert hat, und was Sie – der Reihe nach – tun sollten, wenn der lokale Zustand inkonsistent aussieht.

​
Welcher Befehl, wann

Für die tägliche lokale Iteration sollten Sie fast immer yarn twenty dev verwenden. Bereitstellen und Veröffentlichen sind zum Ausliefern von Releases gedacht, nicht für den lokalen Entwicklungszyklus.
Sie möchten …BefehlNotizen
Lokal mit Live-Sync iterierenyarn twenty devÜberwacht Ihre Dateien und synchronisiert bei jeder Änderung.
Einmal synchronisieren und beenden (CI, Skripte, Hooks)yarn twenty dev --onceFührt einen Build und einen Sync aus und beendet sich anschließend.
Änderungen anzeigen, ohne sie anzuwendenyarn twenty dev --once --dry-runBerechnet und druckt das Diff; schreibt nichts.
Die App aus dem Workspace entfernenyarn twenty app:uninstallFügen Sie --yes hinzu, um die Abfrage zu überspringen.
Einen Tarball an einen Server ausliefernyarn twenty app:publish --privateErfordert eine strikt höhere package.json-Version – siehe Veröffentlichen.
Im Marketplace (npm) veröffentlichenyarn twenty app:publish—
Eine bereitgestellte Version installieren/aktualisierenyarn twenty app:installInstalliert die aktuell bereitgestellte Version.
Den lokalen Server zurücksetzen und sauber neu startenyarn twenty docker:resetLöscht alle lokalen Daten – letztes Mittel.

​
Lokaler Sync benötigt keinen Versionssprung

Die strikt steigende version-Regel (VERSION_ALREADY_EXISTS beim Deploy, APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION bei der Installation) gilt für app:publish / app:install – den Release-Pfad. yarn twenty dev synchronisiert Ihr Manifest an Ort und Stelle und erfordert niemals eine Versionsänderung, sodass Sie package.json nicht anfassen müssen, um zu iterieren. Wenn Sie die Version erhöhen, um eine lokale Änderung zu testen, verwenden Sie den Release-Pfad, obwohl Sie den Entwicklungszyklus benötigen.

​
Die Sync-Ausgabe lesen

Jeder Sync gibt die Metadatenänderungen aus, die er angewendet hat (oder anwenden würde, mit --dry-run): 
Metadata changes: 2 created, 1 updated, 1 deleted
  created objectMetadata rocket
  created fieldMetadata timelineActivities
  updated fieldMetadata launchedAt
  deleted pageLayout legacyTab
✓ Synced
Dies ist Ihre erste Diagnose: Sie zeigt Ihnen genau, welche Objekte, Felder und Layouts sich geändert haben, sodass Sie bestätigen können, dass ein Sync das Erwartete getan hat, bevor Sie die UI prüfen. Wenn ein Sync bei einer einzelnen Entität fehlschlägt, nennt der Fehler die betreffende Entität und ihren universalIdentifier, zum Beispiel: 
Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
Verwenden Sie diesen Bezeichner, um die Entität in Ihrem Manifest (und bei Bedarf im Workspace) zu finden, anstatt zu raten, welche in Konflikt steht.

​
Änderungen vorab ansehen (Dry Run)

yarn twenty dev --once --dry-run baut Ihr Manifest, fragt den Server nach dem Migrationsplan und gibt ihn aus – ohne irgendetwas anzuwenden. Dies ist der sichere Weg, um zu beantworten: “Was würde dieser Sync ändern?”, bevor Sie sich darauf festlegen. 
yarn twenty dev --once --dry-run

Building manifest...
Computing metadata diff (dry run, nothing will be applied)...
Metadata changes: 1 created, 1 updated
  created fieldMetadata timelineActivities
  updated objectMetadata rocket
✓ Dry run complete for My App — no changes were applied
Ein Dry Run:
  • Schreibt nichts – keine Metadatenmigration, kein Update von App-Einträgen, keine Änderungen an Standardrollen/-Tabs und keine API-Client-Generierung.
  • Liefert dasselbe Diff, das ein echter Sync anwenden würde, sodass Sie erstellte/aktualisierte/gelöschte Entitäten im Voraus prüfen können.
  • Ist nützlich vor einer riskanten Änderung, bei der Überprüfung einer KI-generierten Änderung oder in einem Skript, das fehlschlagen soll, wenn eine unerwartete Änderung kurz vor der Anwendung steht.
Ein Dry Run zeigt nur Metadaten-Änderungen an und erfordert, dass die App mindestens einmal synchronisiert wurde (damit der Workspace sie kennt). Wenn Sie ihn gegen eine App ausführen, die noch nie synchronisiert wurde, meldet der Server, dass die App nicht installiert ist – führen Sie zuerst einmal yarn twenty dev aus.

​
Wiederherstellungsleiter

Wenn lokale Metadaten falsch aussehen, eskalieren Sie in dieser Reihenfolge und stoppen Sie, sobald Sie nicht mehr blockiert sind. Jeder Schritt ist störender als der vorherige.
  1. Erneut synchronisieren. Führen Sie yarn twenty dev --once erneut aus. Syncs sind idempotent – das erneute Ausführen eines sauberen Manifests ist sicher und löst oft eine vorübergehende Störung.
  2. Plan ansehen. Führen Sie yarn twenty dev --once --dry-run aus, um genau zu sehen, was der nächste Sync zu ändern beabsichtigt, ohne es anzuwenden.
  3. Benannten Fehler lesen. Wenn ein Sync fehlschlägt, notieren Sie sich den Metadatentyp und den universalIdentifier in der Meldung (siehe oben) und lokalisieren Sie diese Entität in Ihrem Manifest. Ein Konflikt weist in der Regel auf einen doppelten oder wiederverwendeten Bezeichner hin.
  4. Deinstallieren und neu installieren. yarn twenty app:uninstall, dann erneut synchronisieren (yarn twenty dev). Dies baut die Metadaten der App aus einem sauberen Zustand wieder auf, während der Rest Ihres Workspaces intakt bleibt.
  5. Vollständiger Reset (letztes Mittel). yarn twenty docker:reset, dann erneut seeden und synchronisieren.
yarn twenty docker:reset löscht alle Daten in Ihrer lokalen Instanz – jeden Workspace, jeden Eintrag und jede App. Verwenden Sie ihn nur, wenn die vorherigen Schritte fehlgeschlagen sind.
Auf einen Metadatenfehler gestoßen? Bitte öffnen Sie ein Issue und fügen Sie die fehlerhafte Migrationsmeldung (mit ihrem Metadatentyp und universalIdentifier), die Metadata changes-Ausgabe aus dem Sync sowie die von Ihnen ausgeführten Befehle bei.

​
Gleichzeitige Syncs auf einem Workspace vermeiden

Syncing wendet Metadatenmigrationen an. Mehrere Sync-, Deploy- oder Installationsvorgänge gleichzeitig gegen denselben Workspace auszuführen – zum Beispiel mehrere Terminals oder KI-Agenten, die parallel iterieren – kann diese Migrationen verschachteln und Metadaten in einem teilweise angewendeten Zustand zurücklassen. Der Server serialisiert Syncs pro Workspace, um dies zu verhindern, aber Sie sollten dennoch sensible Metadatenoperationen über einen einzelnen Prozess leiten, anstatt sie gleichzeitig auszulösen. Wenn Sie die Entwicklung mit mehreren Agenten orchestrieren, leiten Sie deren Sync-/Deploy-/Install-Aufrufe durch eine Queue, sodass immer nur einer gleichzeitig läuft.

​
Fehler voneinander unterscheiden

Wenn etwas schiefläuft, ermöglichen Ihnen das Metadaten-Diff und benannte Fehler, den Fehler einzuordnen:
  • Manifest-Build-Fehler – die CLI schlägt vor dem Sync fehl (MANIFEST_BUILD_FAILED, TYPECHECK_FAILED); beheben Sie den Quellcode Ihrer App.
  • Sync-/Migrationsfehler – der Build ist erfolgreich, aber das Anwenden des Diffs schlägt fehl und nennt die Entität und den universalIdentifier; beheben Sie die widersprüchlichen Metadaten.
  • App-Code-Laufzeitfehler — die Synchronisierung ist erfolgreich, aber Ihre Logikfunktionen oder Komponenten verhalten sich zur Laufzeit unerwartet; überprüfen Sie die Funktionsprotokolle.
  • Lokaler Instanzzustand — nichts davon trifft zu und der Workspace sieht immer noch falsch aus; arbeiten Sie die Wiederherstellungsleiter nach unten ab.