74 lines
3.9 KiB
Markdown
74 lines
3.9 KiB
Markdown
---
|
||
title: Диагностика
|
||
weight: 1
|
||
---
|
||
|
||
**Цель:** Определить и устранить распространенные ловушки при разработке Quetza.
|
||
|
||
## 1. Сбои при обнаружении модулей
|
||
|
||
**Симптом:** Бот запускается, но ваш модуль игнорируется.
|
||
**Причина:** Нарушение соглашений файловой системы.
|
||
|
||
{{% details title="Чек-лист: Структура директорий" closed="false" %}}
|
||
|
||
- [ ] Существует ли `src/modules/<name>/`?
|
||
- [ ] Экспортирует ли `module.ts` переменную `name`?
|
||
- [ ] Находятся ли команды в `commands/` (а не в `cmds/`)?
|
||
- [ ] Запустили ли вы `pnpm build`? (Quetza запускается из `dist/`).
|
||
{{% /details %}}
|
||
|
||
## 2. Проблемы с регистрацией команд
|
||
|
||
**Симптом:** Команда `/command` не появляется в Discord.
|
||
|
||
### Глобальная регистрация против регистрации в тестовой гильдии (Guild)
|
||
|
||
- **Глобальная:** Команды, отправленные в приложение глобально, могут обновляться до 1 часа и подчиняются более строгим ограничениям скорости (rate limits).
|
||
- **Тестовая гильдия:** Quetza автоматически отправляет команды в конкретную гильдию в режиме разработки для мгновенного обновления.
|
||
- **Требование:** Убедитесь, что `NODE_ENV=development` и `DEV_GUILD_ID` корректно установлены в вашем `.env`.
|
||
|
||
### Ограничения скорости (Rate Limits)
|
||
|
||
Частые обновления глобальных команд могут вызвать ограничения скорости со стороны Discord. Используйте тестовую гильдию для итеративной разработки.
|
||
|
||
## 3. Ошибки взаимодействия (Interaction Failures)
|
||
|
||
**Симптом:** «Приложение не отвечает».
|
||
**Причина:** Выполнение команды заняло более 3 секунд без отложенного ответа (deferral).
|
||
|
||
**Решение:**
|
||
|
||
```typescript
|
||
// ПЛОХО
|
||
await longRunningTask();
|
||
await interaction.reply('Готово'); // Слишком поздно!
|
||
|
||
// ХОРОШО
|
||
await interaction.deferReply();
|
||
await longRunningTask();
|
||
await interaction.editReply('Готово');
|
||
```
|
||
|
||
## 4. Утечки состояния
|
||
|
||
**Симптом:** Потребление памяти ботом растет; странности во взаимодействии между серверами.
|
||
**Причина:** Хранение состояния глобально вместо уровня гильдии.
|
||
|
||
**Диагностика:**
|
||
Проверьте ваш контроллер.
|
||
|
||
- ❌ `private player: AudioPlayer;` (Общий для всех!)
|
||
- ✅ `private players = new Map<string, AudioPlayer>();` (Разделен по ID гильдии).
|
||
|
||
## 5. Обработка событий
|
||
|
||
**Симптом:** События срабатывают несколько раз или не срабатывают вовсе.
|
||
|
||
- **Несколько раз:** События являются аддитивными. Не зарегистрировали ли вы один и тот же обработчик в двух модулях?
|
||
- **Ни разу:** Правильно ли вы экспортировали `name` и `execute`?
|
||
|
||
> [!TIP]
|
||
> **Debug Mode:**
|
||
> Включите подробное логирование, чтобы точно увидеть, какие модули и команды загружаются при запуске.
|