FAQ и проблемы

Панель пишет «Ждём агента deffector»

Панель открыта, но страница не отвечает. Проверьте по порядку:

1. Импорт. import '@deffector/agent' должен быть в коде, который выполняется на странице, — лучше всего первой строкой входного файла. После добавления перезагрузите страницу.
2. Продакшен-сборка. В продакшене каждая точка входа агента намеренно ничего не делает («Продакшен-сборка? Там агент намеренно ничего не делает.»). Используйте dev-сервер.
3. Расширение перезагружено (после npm run build). Content script старой версии теряет связь: перезагрузите страницу и откройте DevTools заново.
4. Адрес не localhost. Там расширению один раз нужно ваше разрешение: панель покажет «У deffector нет доступа к хосту» — нажмите Разрешить на этом сайте.
5. iframe. Content script работает только в верхнем фрейме; приложение внутри iframe не подключается.

Иконка расширения подсказывает то же самое с первого взгляда: серая и «Агент deffector не найден» во всплывающем окне — или цветная, с «effector версия найден» и покрытием sid.

В DevTools нет вкладки deffector

Расширение не загружено, или DevTools открыли раньше, чем оно загрузилось. Проверьте chrome://extensions (или about:debugging в Firefox), затем закройте и снова откройте DevTools. Firefox удаляет временные дополнения при перезапуске — загрузите его снова.

В логе нет первых действий

Агент пишет 10 секунд после загрузки, а затем встаёт на паузу до подключения панели (Health: «История до открытия панели не записана»). Сначала откройте DevTools, потом перезагрузите страницу, или задайте attachDeffector({ whileClosed: 'record' }). См. Производительность.

Новые транзакции перестали появляться

• Запись на паузе? Тогда статус в панели инструментов пишет «запись на паузе» — нажмите кнопку записи.
• Их не перехватывает сохранённый фильтр с Не записывать?
• Другой инструмент занял инспектор effector? У effector один слот инспектора; им пользуются effector-logger и @effector/redux-devtools-adapter. Health показывает Другой инструмент перехватил инспектор effector — нажмите Вернуть или импортируйте другой инструмент до @deffector/agent.

Части юнитов нет, или видны два разных effector

Агент подключается к той копии effector, которую импортирует сам. Если в сборке две копии (слинкованный пакет, монорепозиторий с двумя версиями), юниты другой копии не видны. Объедините effector в сборщике — в Vite resolve: { dedupe: ['effector', 'effector-react'] }. В Next.js держите effector в serverExternalPackages для сервера.

Юниты называются $store@index.js:97, или Health пишет, что у сторов нет sid

Код собран без effector/babel-plugin или @effector/swc-plugin. deffector работает, но с меньшими подробностями; см. Без babel/swc-плагина.

Перемещение во времени запускает мои watchers и эффекты

Приложение в глобальном режиме (без fork()) или рендерится без адаптера deffector, поэтому переходы записывают значения на месте. Используйте fork() и DeffectorProvider — см. Перемещение во времени.

«Пропустить», «Тихо, через fork» или «Воспроизвести в новом scope» ведут себя иначе

Им нужен scope, который deffector может переключить: fork() плюс адаптер. Без него Пропустить и Тихо, через fork недоступны, а воспроизведение записывает начальное состояние на месте.

Страница накрыта, и по ней нельзя кликнуть

Приложение показывает прошлое, и страница заблокирована, чтобы клик его не изменил. Нажмите Esc на странице или Вернуться в настоящее, либо Разрешить клики, чтобы работать в ветке. lockPast: false отключает блокировку.

Трейс воспроизводится с пропущенными шагами

В принимающей сборке нет некоторых юнитов (проверка совместимости показывает их красным), или их sid сдвинулись и они сопоставлены по имени (жёлтым). По возможности записывайте и воспроизводите на одном коммите и задайте attachDeffector({ build }), чтобы проверка предупреждала о разных сборках.

«Свой хендлер» в подмене эффектов выдаёт ошибку

Код хендлера компилируется в странице через new Function; Content Security Policy без unsafe-eval это запрещает. Используйте другие режимы подмены или ослабьте CSP в разработке.

Отдельное приложение не видит агента

• Процесс должен вызвать attachDeffectorNode() до создания юнитов и не должен работать с NODE_ENV=production (или передайте skipInProduction: false).
• [deffector] no WebSocket implementation — Node старше 22: передайте WebSocket из пакета ws.
• Другая машина или телефон: запустите приложение с --host 0.0.0.0 и укажите в url адрес своего компьютера.
• Агентов несколько: выберите нужного в списке Агент над панелью.

deffector куда-то отправляет мои данные?

Нет. Агент общается с панелью в том же браузере (через расширение) или с отдельным приложением, которое вы запускаете сами и которое по умолчанию слушает 127.0.0.1. Своего сервера у deffector нет. Трейс покидает вашу машину, только если вы сами отправите файл, а значения под ключами, похожими на секреты, в нём замаскированы.

Можно ли оставить импорт в продакшен-коде?

Да. В продакшен-сборке каждая точка входа — пустышка с тем же API, а @deffector/agent/node ничего не делает при NODE_ENV=production.

Какие версии поддерживаются?

effector 22.6 и новее (разработка велась на 23.4.4, проверено и на 22.8.6); React 16.8+, Vue 3.0+, Solid 1.3+; Chrome и Edge 116+, Firefox 140+. Полная таблица — с Node, TypeScript и сборщиками — в Установка → Требования.