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

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

Для повседневной локальной разработки вам почти всегда нужна команда yarn twenty dev. Развертывание и публикация предназначены для выпуска релизов, а не для локального цикла разработки.
yarn twenty dev --once и yarn twenty dev --once --dry-run по-прежнему работают как устаревшие псевдонимы для yarn twenty apply и yarn twenty plan.

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

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

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

Каждая синхронизация выводит изменения метаданных, которые она применила (или применила бы, с plan), в стиле Terraform — по одному блоку на сущность с её атрибутами, затем строку с итогами:
Это ваша первая диагностическая точка: она показывает, какие именно объекты, поля и макеты изменились, чтобы вы могли подтвердить, что синхронизация сделала то, что вы ожидали, до проверки в интерфейсе. Разрушительные изменения (to destroy) перечисляются вместе с тем, что они удаляют (например, objectMetadata "auditNote" — drops the table and all its rows) и требуют интерактивного подтверждения или --force в скриптах. Когда синхронизация завершается с ошибкой на одной сущности, в сообщении указываются проблемная сущность и её universalIdentifier, например:
Используйте этот идентификатор, чтобы найти сущность в своем манифесте (и, при необходимости, в рабочем пространстве), вместо того чтобы гадать, какая из них конфликтует.

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

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

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

Когда локальные метаданные выглядят неверно, действуйте поэтапно в следующем порядке и останавливайтесь, как только проблема решена. Каждый следующий шаг более разрушителен, чем предыдущий.
  1. Повторно синхронизируйте. Снова выполните yarn twenty apply. Синхронизации идемпотентны — повторный запуск корректного манифеста безопасен и часто устраняет временный сбой.
  2. Просмотрите план. Выполните yarn twenty plan, чтобы увидеть, что именно намеревается изменить следующая синхронизация, не применяя эти изменения.
  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; исправьте конфликтующие метаданные.
  • Ошибка размера зависимостей — синхронизация или установка завершается сбоем, потому что продакшен‑зависимости приложения (dependencies) слишком велики, чтобы их установить в качестве слоя среды выполнения (LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED); перенесите пакеты, которые ваши логические функции не импортируют во время выполнения (UI-библиотеки, инструменты разработки), в devDependencies.
  • Ошибка выполнения кода приложения — синхронизация проходит успешно, но ваши логические функции или компоненты ведут себя неправильно во время выполнения; проверьте журналы функций.
  • Локальное состояние экземпляра — ни один из вышеперечисленных пунктов не подходит, и рабочее пространство всё ещё выглядит неправильно; двигайтесь вниз по лестнице восстановления.