Перейти к основному содержанию
Локальная разработка приложения строится вокруг синхронизации: CLI пересобирает ваш манифест, а сервер применяет только разницу между ним и метаданными, которые уже есть в вашем рабочем пространстве. На этой странице описано, какую команду выбрать, как читать, что изменила синхронизация, и что делать — по шагам — когда локальное состояние выглядит несогласованным.

​
Какую команду и когда использовать

Для повседневной локальной разработки вам почти всегда нужна команда yarn twenty dev. Развертывание и публикация предназначены для выпуска релизов, а не для локального цикла разработки.
Вы хотите…КомандаЗаметки
Выполнять локальные итерации с синхронизацией в реальном времениyarn twenty devОтслеживает ваши файлы и синхронизирует при каждом изменении.
Выполнить одну синхронизацию и выйти (CI, скрипты, хуки)yarn twenty dev --onceОдна сборка + синхронизация, затем завершение работы.
Предпросмотр изменений без их примененияyarn twenty dev --once --dry-runВычисляет и выводит diff; ничего не записывает.
Удалить приложение из рабочего пространстваyarn twenty app:uninstallДобавьте --yes, чтобы пропустить запрос подтверждения.
Отправить на сервер tar-архивyarn twenty app:publish --privateТребуется строго более высокая версия в package.json — см. Публикация.
Опубликовать на маркетплейсе (npm)yarn twenty app:publish—
Установить / обновить развернутую версиюyarn twenty app:installУстанавливает версию, которая сейчас развернута.
Очистить локальный сервер и начать с нуляyarn twenty docker:resetУдаляет все локальные данные — крайняя мера.

​
Для локальной синхронизации не нужно повышать версию

Правило строго возрастающей version (VERSION_ALREADY_EXISTS при deploy, APP_ALREADY_INSTALLED / CANNOT_DOWNGRADE_APPLICATION при install) относится к app:publish / app:install — пути релизов. yarn twenty dev синхронизирует ваш манифест на месте и никогда не требует изменения версии, поэтому вам не нужно трогать package.json, чтобы делать итерации. Если вы ловите себя на том, что поднимаете версию, чтобы протестировать локальное изменение, значит вы используете релизный путь, когда вам нужен цикл разработки (dev loop).

​
Чтение вывода синхронизации

Каждая синхронизация выводит изменения метаданных, которые она применила (или применила бы, с --dry-run): 
Metadata changes: 2 created, 1 updated, 1 deleted
  created objectMetadata rocket
  created fieldMetadata timelineActivities
  updated fieldMetadata launchedAt
  deleted pageLayout legacyTab
✓ Synced
Это ваша первая диагностическая точка: она показывает, какие именно объекты, поля и макеты изменились, чтобы вы могли подтвердить, что синхронизация сделала то, что вы ожидали, до проверки в интерфейсе. Когда синхронизация завершается с ошибкой на одной сущности, в сообщении указываются проблемная сущность и её universalIdentifier, например: 
Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
Используйте этот идентификатор, чтобы найти сущность в своем манифесте (и, при необходимости, в рабочем пространстве), вместо того чтобы гадать, какая из них конфликтует.

​
Предпросмотр изменений (dry run)

yarn twenty dev --once --dry-run собирает ваш манифест, запрашивает у сервера план миграции и выводит его — без применения чего-либо. Это безопасный способ ответить на вопрос «что изменит эта синхронизация?» до того, как вы на неё согласитесь. 
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
Пробный запуск (dry run):
  • Ничего не записывает — ни миграции метаданных, ни обновления записи приложения, ни изменений ролей/вкладок по умолчанию, ни генерации API‑клиента.
  • Возвращает тот же diff, который применит реальная синхронизация, чтобы вы могли заранее просмотреть создаваемые/обновляемые/удаляемые сущности.
  • Полезен перед рискованным изменением, при проверке изменения, сгенерированного ИИ, или в скрипте, который должен завершаться с ошибкой, если вот-вот будет применено неожиданное изменение.
Пробный запуск предварительно показывает только изменения метаданных и требует, чтобы приложение хотя бы один раз уже было синхронизировано (чтобы рабочее пространство знало о нём). Если вы запускаете его для приложения, которое никогда не синхронизировалось, сервер сообщит, что приложение не установлено — сначала один раз выполните yarn twenty dev.

​
Лестница восстановления

Когда локальные метаданные выглядят неверно, действуйте поэтапно в следующем порядке и останавливайтесь, как только проблема решена. Каждый следующий шаг более разрушителен, чем предыдущий.
  1. Повторно синхронизируйте. Снова выполните yarn twenty dev --once. Синхронизации идемпотентны — повторный запуск корректного манифеста безопасен и часто устраняет временный сбой.
  2. Просмотрите план. Выполните yarn twenty dev --once --dry-run, чтобы увидеть, что именно намеревается изменить следующая синхронизация, не применяя эти изменения.
  3. Прочитайте сообщение об ошибке. Если синхронизация завершается с ошибкой, обратите внимание на тип метаданных и universalIdentifier в сообщении (см. выше) и найдите эту сущность в своем манифесте. Конфликт обычно указывает на дублированный или повторно используемый идентификатор.
  4. Удалите и переустановите. Выполните yarn twenty app:uninstall, затем синхронизируйте снова (yarn twenty dev). Это пересобирает метаданные приложения с нуля, сохраняя остальную часть вашего рабочего пространства нетронутой.
  5. Полный сброс (крайняя мера). Выполните yarn twenty docker:reset, затем заново выполните начальное наполнение данными и синхронизацию.
yarn twenty docker:reset удаляет все данные в вашей локальной инсталляции — все рабочие пространства, записи и приложения. Используйте его только после того, как предыдущие шаги не помогли.
Столкнулись с ошибкой метаданных? Пожалуйста, создайте issue и приложите сообщение о сбое миграции (с типом метаданных и universalIdentifier), вывод Metadata changes из синхронизации и команды, которые вы запускали.

​
Избегайте одновременных синхронизаций в одном рабочем пространстве

Синхронизация применяет миграции метаданных. Запуск нескольких операций sync, deploy или install по отношению к одному и тому же рабочему пространству одновременно — например, из нескольких терминалов или при параллельных итерациях агентов ИИ — может перемешать эти миграции и оставить метаданные в частично примененном состоянии. Сервер последовательно обрабатывает синхронизации для каждого рабочего пространства, чтобы предотвратить это, но вам всё равно следует пропускать чувствительные операции с метаданными через один процесс, а не запускать их параллельно. Если вы организуете разработку с несколькими агентами, направляйте их вызовы sync/deploy/install через одну очередь, чтобы в каждый момент времени выполнялась только одна операция.

​
Как различать типы сбоев

Когда что‑то идёт не так, diff метаданных и именованные ошибки помогают определить, на каком этапе произошел сбой:
  • Ошибка сборки манифеста — CLI завершается с ошибкой до синхронизации (MANIFEST_BUILD_FAILED, TYPECHECK_FAILED); исправьте исходный код приложения.
  • Ошибка синхронизации / миграции — сборка проходит успешно, но применение diff завершается сбоем с указанием сущности и universalIdentifier; исправьте конфликтующие метаданные.
  • Ошибка выполнения кода приложения — синхронизация проходит успешно, но ваши логические функции или компоненты ведут себя неправильно во время выполнения; проверьте журналы функций.
  • Локальное состояние экземпляра — ни один из вышеперечисленных пунктов не подходит, и рабочее пространство всё ещё выглядит неправильно; двигайтесь вниз по лестнице восстановления.