Ошибки npm и node_modules

Если игровой режим использует сторонние библиотеки, рядом с проектом обычно находятся:

package.json
package-lock.json
node_modules\

Перейдите в каталог с package.json и выполните:

npm install

Для восстановления точных версий из lock-файла:

npm ci

Не устанавливайте зависимости в случайном каталоге. Сервер должен находить node_modules относительно используемого проекта.

Перенос с Windows на Linux

Не копируйте старые нативные модули без переустановки. Удалите node_modules и выполните установку зависимостей на целевой системе.

После обновления библиотеки появились ошибки

Верните рабочий package-lock.json и установите прежние версии. Обновление всех зависимостей может изменить API, формат модулей и требования к Node.js.

Не работают события и команды JavaScript

Убедитесь, что файл обработчиков подключается:

// packages/gamemode/index.js
require('./events');
require('./commands');

Добавьте контрольные сообщения:

console.log('[events] Начало загрузки');

mp.events.add('playerJoin', (player) => {
 console.log(`[events] playerJoin: ${player.name}`);
});

console.log('[events] Обработчики зарегистрированы');

Асинхронные ошибки

async function loadAccount(player) {
 try {
 const account = await findAccount(player.name);

 if (!account) {
 console.warn(`[account] Не найден: ${player.name}`);
 return;
 }

 console.log(`[account] Загружен: ${player.name}`);
 } catch (error) {
 console.error('[account] Ошибка загрузки:', error);
 }
}

Не используйте пустой catch. Он скрывает причину ошибки и усложняет поиск несохранённых данных.

Как найти проблемный пакет

1. Отключите необязательные ресурсы.
2. Запустите сервер с базовым пакетом.
3. Возвращайте остальные ресурсы небольшими группами.
4. После появления ошибки разделите последнюю группу.
5. Продолжайте до обнаружения конкретного файла.

Ошибки серверных пакетов C#

C#-ресурсы работают через Bridge и связанную среду выполнения. DLL может не загрузиться из-за несовместимой версии Bootstrapper, .NET или отсутствующей зависимости.

Проверьте:

• включён ли C# в конфигурации;
• присутствует ли каталог bridge;
• не повреждены ли его файлы;
• совпадает ли версия Bootstrapper.dll;
• подходит ли целевая версия .NET;
• скопированы ли зависимости ресурса;
• совпадает ли архитектура;
• не заблокировала ли DLL защита Windows.

{
 "csharp": true
}

На JavaScript-сервере без C#-ресурсов этот параметр лучше не включать.

Несовместимый Bootstrapper

Типичные сообщения:

TargetParameterCountException
Parameter count mismatch
Could not load type
Unable to load one or more requested types

Порядок исправления:

1. Остановите сервер.
2. Обновите серверные файлы одной совместимой сборкой.
3. Возьмите Bootstrapper из текущего bridge\runtime.
4. Обновите ссылку в C#-проекте.
5. Очистите bin и obj.
6. Пересоберите проект.
7. Не возвращайте старый Bridge поверх новой версии.

Ошибка версии .NET

Возможные сообщения:

• TypeLoadException;
• FileLoadException;
• FileNotFoundException;
• Could not load assembly;
• Framework not found.

Игровой режим должен собираться под версию .NET, совместимую с текущим Bridge.

dotnet clean
dotnet build -c Release

Could not load file or assembly

Проверьте наличие библиотеки, её версию, копирование в выходной каталог, архитектуру и нативные зависимости операционной системы.

Если проект работает только на компьютере разработчика, разверните его в пустой тестовой папке. Так обнаружатся DLL, которые случайно брались из старого каталога.

C#-события не вызываются

public class Main : Script
{
 public Main()
 {
 NAPI.Util.ConsoleOutput("[C#] Конструктор запущен");
 }

 [ServerEvent(Event.ResourceStart)]
 public void OnResourceStart()
 {
 NAPI.Util.ConsoleOutput("[C#] Ресурс запущен");
 }
}

Если нет сообщения конструктора, сборка не загружена. Если конструктор работает, но событие не вызывается, проверяйте атрибут, Bootstrapper и исключения регистрации.

RAGE MP Server не подключается к базе данных

Сначала проверьте подключение к СУБД отдельно от игрового режима. Используйте те же данные в официальном клиенте базы или консольной утилите.

Проверьте:

• запущена ли служба MySQL или MariaDB;
• правильно ли указан host;
• правильно ли указан порт;
• существуют ли пользователь и база;
• верен ли пароль;
• разрешено ли подключение с адреса сервера;
• открыт ли порт базы;
• установлен ли драйвер Node.js или .NET;
• применены ли миграции.

Пример подключения MySQL

const mysql = require('mysql');

const connection = mysql.createConnection({
 host: process.env.DB_HOST || '127.0.0.1',
 port: Number(process.env.DB_PORT || 3306),
 user: process.env.DB_USER,
 password: process.env.DB_PASSWORD,
 database: process.env.DB_NAME,
 charset: 'utf8mb4'
});

ECONNREFUSED

Соединение не принимается по указанному адресу и порту.

Проверьте:

• работает ли служба базы;
• слушает ли она нужный интерфейс;
• правильно ли указан порт;
• не используется ли localhost внутри другого контейнера;
• разрешён ли трафик firewall;
• доступна ли база по сети.

Если база находится на другом VPS, 127.0.0.1 указывает на сам игровой сервер, а не на удалённую СУБД.

Проверка Windows:

Test-NetConnection DB_HOST -Port 3306

Проверка Linux:

nc -vz DB_HOST 3306

Access denied for user

Проверьте имя пользователя, пароль, разрешённый host и права на выбранную базу.

'game'@'localhost'

и:

'game'@'10.0.0.%'

могут рассматриваться MySQL как разные учётные записи.

Не выдавайте игровому серверу административные права на всю СУБД. Создайте отдельного пользователя с доступом только к необходимой базе.

Connection timeout и Lost connection

Причины:

• недоступный сервер базы;
• сетевой разрыв;
• перегрузка СУБД;
• медленный запрос;
• закрытие неактивного соединения;
• исчерпание пула;
• перезапуск базы.

Не увеличивайте таймаут бесконечно. Сначала определите, зависает подключение или конкретный SQL-запрос.

const startedAt = Date.now();

connection.query('SELECT 1', (error) => {
 const duration = Date.now() - startedAt;

 if (error) {
 console.error(`[db] Ошибка после ${duration} ms`, error);
 return;
 }

 console.log(`[db] Проверка завершена за ${duration} ms`);
});

Too many connections

Ошибка возникает, если соединения создаются для каждого запроса, не закрываются или несколько пакетов создают отдельные пулы.

const pool = mysql.createPool({
 connectionLimit: 10,
 host: process.env.DB_HOST,
 user: process.env.DB_USER,
 password: process.env.DB_PASSWORD,
 database: process.env.DB_NAME
});

Не увеличивайте лимит до огромного значения без проверки утечек соединений и памяти.

Table doesn't exist и Unknown column

Сервер подключился к базе, но её структура не соответствует коду. Проверьте выбранную схему, миграции, версию сборки, регистр названий таблиц и полноту импорта дампа.

Перед изменением структуры создайте резервную копию. Случайные ALTER TABLE могут временно убрать ошибку, но повредить данные позже.

Инициализация базы при запуске

async function startApplication() {
 try {
 await connectDatabase();
 await runMigrations();
 registerEvents();

 console.log('[server] Инициализация завершена');
 } catch (error) {
 console.error('[server] Ошибка запуска:', error);
 process.exitCode = 1;
 }
}

startApplication();

Не принимайте игроков до готовности базы и завершения обязательных миграций.

Ошибки client_packages

Клиентские ресурсы находятся в:

server-files\client_packages\

Пример структуры:

client_packages\
├── index.js
└── gamemode\
 ├── index.js
 ├── events.js
 ├── ui\
 │ ├── index.html
 │ ├── app.js
 │ └── style.css
 └── assets\

Корневой файл подключает игровой режим:

require('./gamemode/index');

Клиентский файл не выполняется

mp.gui.chat.push('[client] Пакет загружен');

Если сообщения нет:

• файл не подключён;
• неправильно указан путь;
• у игрока старый кэш;
• ресурсы не загрузились;
• в JavaScript есть синтаксическая ошибка;
• HTTP-порт недоступен.

CEF и http://package/

const browser = mp.browsers.new(
 'http://package/gamemode/ui/index.html'
);

Проверьте регистр символов, расположение HTML-файла и отсутствие локальных путей разработчика.

Интерфейс может работать у разработчика, но не у игроков, если CSS, шрифты или JavaScript загружаются с localhost либо с локального диска.

Downloading Resources

Если игроки зависают при загрузке:

• проверьте HTTP-порт;
• убедитесь, что он не занят другим процессом;
• проверьте права чтения client_packages;
• проверьте свободное место;
• временно отключите FastDL;
• найдите файл, на котором останавливается загрузка;
• проверьте доступ из другой сети.

Если игровой порт работает, но файлы не загружаются, чаще всего недоступен HTTP-порт или неправильно настроен FastDL.

Ошибки FastDL

Проверьте полный URL, HTTPS-сертификат, структуру каталогов, доступ без авторизации, перенаправления и актуальность файлов.

После обновления сервера очистите CDN-кэш. Старый снимок FastDL может продолжить раздавать несовместимые пакеты.

Оптимизация ресурсов

Не добавляйте в client_packages резервные архивы, дампы базы, логи, исходники изображений, серверный node_modules и старые версии интерфейса.

Какие порты использует RAGE MP Server

При стандартной настройке:

"port": 22005

проверяйте:

• 22005/TCP — игровой сервер;
• 22005/UDP — игровой трафик;
• 22006/TCP — HTTP-загрузка клиентских ресурсов.

Если игровой порт изменён на 23000, HTTP-порт обычно будет следующим:

23000/TCP
23000/UDP
23001/TCP

Windows Firewall

New-NetFirewallRule `
 -DisplayName "RAGE MP Game TCP" `
 -Direction Inbound `
 -Protocol TCP `
 -LocalPort 22005 `
 -Action Allow

New-NetFirewallRule `
 -DisplayName "RAGE MP Game UDP" `
 -Direction Inbound `
 -Protocol UDP `
 -LocalPort 22005 `
 -Action Allow

New-NetFirewallRule `
 -DisplayName "RAGE MP Packages HTTP" `
 -Direction Inbound `
 -Protocol TCP `
 -LocalPort 22006 `
 -Action Allow

Проверьте, что правила применяются к активному профилю сети. Сторонний антивирус может использовать собственный сетевой экран.

UFW на Linux

sudo ufw allow 22005/tcp
sudo ufw allow 22005/udp
sudo ufw allow 22006/tcp
sudo ufw status

firewalld

sudo firewall-cmd --permanent --add-port=22005/tcp
sudo firewall-cmd --permanent --add-port=22005/udp
sudo firewall-cmd --permanent --add-port=22006/tcp
sudo firewall-cmd --reload

На облачном VPS также проверьте security group, сетевой ACL и firewall панели хостинга.

Игроки не подключаются к домашнему серверу

Настройте перенаправление портов на локальный IP компьютера:

Закрепите локальный IP через резервирование DHCP. Если адрес компьютера изменится, правила роутера будут направлять трафик на другое устройство.

Проверка внешнего адреса

Проверяйте сервер через мобильный интернет или другую внешнюю сеть. Не каждый роутер поддерживает подключение к собственному внешнему IP из локальной сети.

CGNAT и отсутствие публичного IP

Если WAN-адрес роутера отличается от внешнего IP, провайдер может использовать CGNAT.

Признаки:

• port forwarding настроен, но сервер недоступен;
• WAN-адрес относится к частному диапазону;
• несколько абонентов используют один внешний IP;
• сервер работает только в локальной сети.

Решения:

• заказать публичный IPv4;
• арендовать VPS;
• использовать игровой хостинг;
• настроить туннель с публичным входом;
• уточнить условия у провайдера.

Смена DNS не устраняет CGNAT.

Как проверить доступность портов

Windows

netstat -ano | findstr :22005
netstat -ano | findstr :22006

Linux

ss -lntup | grep -E '22005|22006'

Проверка HTTP-порта с другого компьютера

Test-NetConnection SERVER_IP -Port 22006

или:

nc -vz SERVER_IP 22006

UDP нельзя надёжно проверить обычной TCP-проверкой. Лучший тест — реальное подключение клиента из другой сети.

Порт открыт, но игрок не входит

Проверяйте версию клиента, лимит игроков, авторизацию, бан IP, ошибки базы, клиентские ресурсы и серверные таймауты.

Игрок подключается и сразу отключается

Записывайте этапы подключения:

• сетевое соединение;
• playerJoin;
• проверку аккаунта;
• загрузку персонажа;
• отправку клиентских событий;
• появление в игровом мире;
• причину отключения.

mp.events.add('playerJoin', (player) => {
 console.log(`[join] ${player.name}`);
});

mp.events.add('playerQuit', (player, exitType, reason) => {
 console.log(
 `[quit] ${player.name}; type=${exitType}; reason=${reason}`
 );
});

Ограничьте доступ к журналам и не храните персональные данные дольше необходимого.

Игрок зависает на авторизации

Проверьте ответ базы, обработку отсутствующего аккаунта, внешний API, создание сессии, CEF и клиентское событие открытия интерфейса.

console.time(`[auth] ${player.name}`);

try {
 await loadPlayerAccount(player);
 await loadCharacter(player);

 console.timeEnd(`[auth] ${player.name}`);
} catch (error) {
 console.error(`[auth] ${player.name}`, error);
}

Не выполняйте тяжёлые синхронные операции внутри playerJoin.

Сервер зависает под нагрузкой

Признаки:

• команды выполняются с задержкой;
• растёт ping;
• авторизация занимает минуты;
• процесс загружает одно ядро на 100%;
• постоянно растёт память;
• сервер перестаёт отвечать без завершения процесса.

Проверяйте:

• время обработчиков;
• частоту таймеров;
• количество SQL-запросов;
• индексы таблиц;
• объём данных в событиях;
• бесконечные циклы;
• повторную регистрацию обработчиков;
• частоту сохранения игроков.

Не выполняйте SQL-запрос каждый кадр. Часто используемые данные храните в памяти и сохраняйте контролируемыми операциями.

Ошибки передачи данных между клиентом и сервером

Проверяйте имя события, порядок аргументов, размер объекта и допустимость значений.

mp.events.add('shop:buy', async (player, itemId, amount) => {
 const safeItemId = Number(itemId);
 const safeAmount = Number(amount);

 if (!Number.isInteger(safeItemId)) {
 return;
 }

 if (!Number.isInteger(safeAmount) || safeAmount < 1 || safeAmount > 100) {
 return;
 }

 await buyItem(player, safeItemId, safeAmount);
});

Не доверяйте данным от клиента. Проверяйте цену, количество, права, позицию и идентификаторы на серверной стороне.

Сервер постоянно перезапускается в systemd

systemctl status rageserv
journalctl -u rageserv -n 200 --no-pager

Проверьте рабочий каталог, ExecStart, пользователя службы, переменные окружения, права на пакеты и первую ошибку процесса.

На время диагностики остановите автоматические перезапуски и запустите сервер вручную от того же пользователя.

Ошибки RAGE MP Server в Docker

Проверьте публикацию TCP, UDP и HTTP-порта:

docker run \
 -p 22005:22005/tcp \
 -p 22005:22005/udp \
 -p 22006:22006/tcp \
 rage-server-image

Внутри контейнера 127.0.0.1 указывает на сам контейнер. Для базы в другом контейнере используйте имя её сервиса.

Убедитесь, что пакеты и данные базы сохраняются на подключённых томах, а пароли не записаны в Dockerfile.

Безопасность публичного сервера

• запускайте процесс от отдельного пользователя;
• не открывайте MySQL всему интернету;
• создайте отдельного пользователя базы;
• не храните секреты в client_packages;
• проверяйте клиентские события;
• ограничивайте административные команды;
• используйте параметризованные SQL-запросы;
• создавайте резервные копии;
• ограничивайте доступ к панели управления;
• следите за ошибками и нагрузкой.

Клиент может подменить цену, количество предметов, координаты, идентификатор транспорта и параметры команды. Все важные проверки должны выполняться на сервере.

Сервер сломался после обновления

Проверьте совместимость серверного файла, JavaScript API, C# Bridge, Bootstrapper, .NET, npm-зависимостей, клиентских скриптов и DLC.

Безопасный порядок обновления

1. Создайте резервную копию.
2. Разверните новую версию в отдельной папке.
3. Перенесите конфигурацию.
4. Установите зависимости заново.
5. Пересоберите C# под актуальный Bootstrapper.
6. Запустите чистый тестовый сервер.
7. Добавьте серверные пакеты.
8. Проверьте базу и client_packages.
9. Выполните тест несколькими клиентами.
10. Только затем обновляйте рабочий сервер.

Не заменяйте рабочий каталог без возможности быстрого отката.

Последовательность проверки RAGE MP Server

1. Создайте копию файлов и базы.
2. Запустите сервер через терминал.
3. Сохраните первую ошибку и стек.
4. Проверьте conf.json.
5. Запустите сервер без пакетов.
6. Проверьте bind и занятые порты.
7. Верните один JavaScript-ресурс.
8. Исправьте Cannot find module и SyntaxError.
9. Проверьте CommonJS и ES Modules.
10. Переустановите npm-зависимости.
11. Проверьте события и асинхронные ошибки.
12. Обновите Bridge и Bootstrapper одной версии.
13. Пересоберите C#.
14. Проверьте базу отдельно.
15. Исправьте права пользователя базы.
16. Проверьте миграции и таблицы.
17. Проверьте client_packages и CEF.
18. Откройте игровой TCP- и UDP-порт.
19. Откройте HTTP-порт.
20. Проверьте port forwarding и CGNAT.
21. Проверьте подключение из внешней сети.
22. Проверьте загрузку ресурсов.
23. Добавьте журнал авторизации.
24. Проверьте сервер под нагрузкой.
25. После успешного теста включите announce.

Частые вопросы

Почему сервер сразу закрывается?

Запустите его через CMD или терминал. Причиной обычно является ошибка конфигурации, занятый порт, отсутствующая зависимость или сбой первого пакета.

Где находятся JavaScript-пакеты?

Серверные ресурсы находятся в packages, клиентские — в client_packages.

Что означает Cannot find module?

Node.js не нашёл файл или библиотеку. Проверьте путь, регистр и node_modules.

Почему код работает на Windows, но не на Linux?

Linux различает регистр символов. Также отличаются права, системные библиотеки и нативные npm-модули.

Что означает Unexpected token в conf.json?

В JSON присутствует лишняя запятая, неправильная кавычка, комментарий или незакрытая скобка.

Почему import не работает?

Проект выполняется как CommonJS. Используйте require либо настройте весь проект на совместимый формат ES Modules.

Почему не загружается C#-ресурс?

Проверьте Bridge, Bootstrapper, .NET, архитектуру и отсутствующие DLL.

Почему C#-события перестали работать после обновления?

Проект может ссылаться на старый Bootstrapper. Обновите ссылку, очистите bin и obj и пересоберите DLL.

Почему сервер не подключается к MySQL?

Проверьте службу базы, адрес, порт, пользователя, пароль, разрешённый host и firewall.

Что означает Access denied?

База отклонила пользователя с указанного хоста. Проверьте права учётной записи и пароль.

Что означает Too many connections?

Достигнут лимит подключений. Ищите утечки соединений и лишние пулы.

Почему игроки не скачивают client_packages?

Проверьте HTTP-порт, FastDL, права на файлы и доступность сервера ресурсов.

Какие порты использует сервер?

По умолчанию 22005 TCP/UDP для игры и 22006 TCP для загрузки пакетов.

Почему локально сервер работает, а друзья не подключаются?

Проверьте bind, firewall, port forwarding, внешний IP и CGNAT.

Почему сервер есть по IP, но отсутствует в списке?

Проверьте announce, исходящий доступ и стабильность процесса.

Нужно ли запускать сервер от root?

Нет. Для постоянной работы используйте отдельного пользователя с минимальными правами.

Как быстрее найти проблемный пакет?

Запустите чистый сервер и возвращайте ресурсы небольшими группами, разделяя проблемную группу пополам.