Перейти к основному содержимому

Проверка перед сборкой и CI

Находит потерянные ссылки и незаполненные обязательные поля до выпуска проекта.

Быстрый старт​

Откройте Tools → Aspid 🐍 → FastTools → Settings и выберите Build / CI gate → Fail. Теперь потерянные типы прерывают сборку плеера. По умолчанию стоит Warn.

Проверка сообщает о нарушениях; исправление описано на странице Восстановление SerializeReference.

Проверка перед сборкой​

Строгость проверки задаёт настройка Build / CI gate:

РежимСборка плеераОтдельный CI-запуск
OffПроверка пропускаетсяНи поиска, ни отчёта, старый отчёт остаётся; код 0
WarnПредупреждение, сборка продолжаетсяОтчёт; нарушения в журнале как предупреждения; код 0
FailПотерянные типы прерывают сборкуОтчёт; нарушения в журнале как ошибки; код 1 при нарушениях

Сборка проверяет все ассеты под Assets/, а не только попадающие в неё: в режиме Fail её остановит и неиспользуемый префаб — исключите такие папки в Excluded scan folders.

Что проверяет каждый запуск​

ЗапускПотерянные типыПустые поля с Required = true
Project References → Scan ProjectДа, вместе с ожидающими миграциямиЕсли режим не Off, в разделе Required
Asset ReferencesДаДа, в любом режиме
Сборка плеераЕсли режим не OffНет
CI без -srGateRequiredЕсли режим не OffНет
CI с -srGateRequiredЕсли режим не OffЕсли режим не Off

Раздел Required: пустое поле _primary в двух префабахРаздел Required: пустое поле _primary в двух префабах

Обязательное поле задаёт [TypeSelector(Required = true)], подробнее — в разделе Обязательное поле. В сценах не проверяются обязательные поля внутри managed-ссылок, в коллекциях и в override префабов.

Обнаружение новых поломок​

Breakage detection сообщает о новых потерянных ссылках и именах типов сразу после изменения скриптов, сборок или ассетов — уведомлением, а также в Console. Настройка включена по умолчанию и находится в Tools → Aspid 🐍 → FastTools → Settings, а также в Preferences → Aspid.FastTools → SerializeReference. Это личная настройка: у каждого участника своя.

Область проверки​

  • сохранённые .prefab, .asset, .unity, .controller (Animator Controller) и .playable (Timeline) под Assets/, кроме Excluded scan folders;
  • [SerializeReference] и имена в полях SerializableType и SerializableMonoScript; строки с [TypeSelector] не проверяются;
  • ожидающие миграции с MovedFrom потерянными не считаются;
  • двоичные ассеты, нескачанные файлы Git LFS и файлы, которые не удалось открыть (заблокированы другой программой, нет прав на чтение), не проверяются: Scan Project и проверка сборки предупреждают о них в Console, CI перечисляет их в отчёте; для полного сканирования включите Asset Serialization → Mode → Force Text, скачайте файлы LFS и закройте программу, которая держит заблокированный файл; чтобы CI считал их нарушениями, передайте -srGateStrict.
  • файл, последний раз сохранённый до Unity 2021.2, хранит managed-ссылки в старом формате: сборка и CI предупреждают о нём вместо проверки, пока его не пересохранят, например через AssetDatabase.ForceReserializeAssets().

Excluded scan folders исключает папки из Project References, проверки сборки, CI и обнаружения новых поломок.

Build / CI gate, Excluded scan folders и Auto de-alias duplicated list elements — настройки проекта с фиолетовой полосой. Они хранятся в ProjectSettings/SerializeReferenceSharedSettings.asset, общем для команды и CI, а ещё открываются в Project Settings → Aspid.FastTools → SerializeReference.

Раздел SerializeReference на вкладке Settings: настройки проекта с фиолетовой полосой, личные — с серойРаздел SerializeReference на вкладке Settings: настройки проекта с фиолетовой полосой, личные — с серой

Запуск в CI​

Unity -batchmode -projectPath . \
-executeMethod \
Aspid.FastTools.SerializeReferences.Editors.SerializeReferenceCiGate.RunCheck \
-srGateReport SerializeReferenceGateReport.txt \
-srGateRequired -srGateFail

RunCheck работает только с -batchmode: без него он пишет предупреждение и ничего не проверяет. Код выхода 2 означает сбой самой проверки.

Флаги запуска​

ФлагДействие
-srGateReport <path>Путь отчёта от корня проекта, по умолчанию SerializeReferenceGateReport.txt; папка должна существовать, файл перезаписывается
-srGateRequiredДополнительно проверить незаполненные поля с Required = true
-srGateFailИспользовать Fail вместо режима проекта, даже Off
-srGateWarnOnlyИспользовать Warn вместо режима проекта, даже Off; важнее -srGateFail, если переданы оба
-srGateStrictСчитать нарушениями файлы, которые не удалось проверить (нескачанные файлы Git LFS, двоичные ассеты, способные хранить ссылки, файлы, которые не удалось открыть, файлы, сохранённые до Unity 2021.2); в режиме Warn код выхода остаётся 0

Отчёт​

Отчёт содержит потерянные типы, незаполненные обязательные поля и пропущенные файлы. Пропущенные файлы не меняют код выхода, если не передан -srGateStrict.

В журнале сборки плеера и CI-запуска видны первые 50 нарушений, остальные только подсчитаны. Полный список дают отчёт и Scan Project.

Формат отчёта

Отчёт начинается с заголовка:

# SerializeReference Gate Report
# Violations: 2
# Not scanned: 4
# Binary Assets/Legacy/OldLoadout.prefab
# LfsPointer Assets/Levels/Arena.unity
# Unreadable Assets/Levels/Boss.prefab
# UnsupportedReferencesVersion Assets/Legacy/OldWave.asset

У каждого пропущенного файла указана причина: двоичный файл, нескачанный файл Git LFS, файл, который не удалось открыть (Unreadable: заблокирован другой программой или нет прав на чтение), или managed-ссылки в формате старше Unity 2021.2.

Дальше — по строке на нарушение, поля разделены табуляцией:

KIND assetPath fileId rid className fieldPath origin ns asm
ПолеСодержимое
KINDMissingType, MissingTypeName или RequiredUnset
assetPathПуть файла
fileIdИдентификатор объекта-владельца внутри файла; для override экземпляра префаба — идентификатор экземпляра
ridИдентификатор managed-ссылки; в строках RequiredUnset — -2 для пустого [SerializeReference] и 0 для string и SerializableType; в строках MissingTypeName — managed-ссылка, в которой лежит поле, или 0
classNameСохранённое имя класса для MissingType; сохранённое имя типа целиком для MissingTypeName
fieldPathПуть обязательного поля; поле обёртки для MissingTypeName; для MissingType из override — переопределённое поле; иначе пусто
originoverride для типа, заданного override экземпляра префаба; иначе пусто
nsСохранённое пространство имён для MissingType; иначе пусто
asmСохранённая сборка для MissingType; иначе пусто

В Asset References запись находится по rid, строка RequiredUnset с rid 0 — по fieldPath; строка с origin override — в разделе Prefab instance overrides в Project References. Строка MissingTypeName находится в своей группе type name в Project References.