Руководство по индивидуальной настройке версий Node.js для проектов в ServBay (macOS)

ServBay — это мощная локальная среда веб-разработки, созданная специально для разработчиков. Она предоставляет комплексное решение, интегрируя различные языки программирования, базы данных и веб-серверы, включая Node.js. Одним из ярких преимуществ ServBay является его нативная поддержка и гибкое управление несколькими версиями Node.js. С помощью простого конфигурационного файла вы легко можете определить необходимую версию Node.js для каждого проекта — без использования внешних менеджеров версий вроде NVM, fnm и без Docker-контейнеров. Это заметно упрощает рабочий процесс и предотвращает загрязнение глобального окружения и конфликты версий.

В этой статье вы узнаете, как с помощью файла .servbay.config реализовать контроль версии Node.js на уровне каждого проекта.

Почему для управления Node.js-версиями стоит выбрать .servbay.config от ServBay?

Традиционные методы управления версиями Node.js, например, с помощью NVM или ручной установки, могут создавать ряд неудобств:

• Глобальное загрязнение и конфликты: Установка версий в систему или глобальное переключение через менеджер версий часто приводит к тому, что зависимости разных проектов конфликтуют между собой.
• Время на установку и компиляцию: Переустановка или переход между архитектурами (например, x86_64 и arm64) зачастую требуют перекомпиляции модулей, что отнимает время и усложняет процесс.
• Оверхед от Docker: Если нужен только определённый Node.js для проекта, запускать полноценный контейнер Docker — излишнее усложнение.

ServBay решает эти задачи за счёт предустановленных версий Node.js (сейчас поддерживаются все минорные версии с v12 до v23 — доступные для управления в разделе «Пакеты» приложения ServBay) в сочетании с файлом .servbay.config:

• Мгновенное переключение: Все версии уже предустановлены, переключение происходит практически мгновенно.
• Изоляция проектов: Настройка действует только в пределах каталога проекта, обеспечивая настоящую изоляцию версий для каждого проекта.
• Без глобального загрязнения: Системная среда не изменяется, ваша macOS остаётся чистой.
• Интеграция с ServBay: Бесшовная работа с другими пакетами ServBay (PHP, базы данных, веб-серверы и др.).

Предварительные требования

Перед началом убедитесь, что:

1. ServBay установлен и запущен на вашем macOS.
2. В разделе «Пакеты» (Packages) приложения ServBay нужная версия Node.js для вашего проекта уже активирована.
3. У вас есть каталог проекта, для которого вы хотите задать определённую версию Node.js.

Основной принцип работы

ServBay отслеживает текущую директорию в интегрированном терминале. Когда вы используете команду cd для перехода между папками, ServBay ищет в текущем и родительских каталогах файл с именем .servbay.config. Как только он найден (приоритет у самого ближнего к текущей директории), ServBay считывает настройки и динамически подстраивает переменные окружения текущей терминальной сессии, например, обновляет переменную PATH так, чтобы использовалась именно та версия Node.js, что указана в .servbay.config.

Благодаря этому механизму, терминальные сессии в разных каталогах автоматически загружают и используют указанные для каждого проекта версии Node.js, без необходимости ручного переключения.

Шаги настройки

Настроить индивидуальную версию Node.js для проекта очень просто — всего два шага:

Шаг 1: Создайте и отредактируйте файл .servbay.config

В корневом каталоге вашего проекта (обычно это папка с файлом package.json) создайте новый файл с именем .servbay.config.

Откройте его в любимом текстовом редакторе и добавьте, например, такие строки:

# Указать основную версию Node.js для проекта
# ServBay автоматически выберет последнюю доступную минорную версию этого мажорного релиза
NODE_VERSION=20

# (По желанию) Настроить зеркала npm или pnpm для ускорения установки зависимостей
# Для пользователей из России и СНГ можно рассмотреть альтернативные зеркала, либо оставить по умолчанию
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# (По желанию) Указать папку для кеша npm или pnpm
# Рекомендуется использовать временную директорию ServBay для экономии места и чистоты окружения
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

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

• NODE_VERSION: обязательный параметр. Определяет мажорную версию Node.js, которую требует ваш проект. Например, если указать 20, будет выбрана последняя установленная версия Node.js 20.x. Обязательно проверьте, что данная версия установлена в ServBay.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: опционально. Позволяет указать зеркало реестра пакетов для Yarn или npm, существенно ускоряя установку зависимостей при нестабильном интернет-соединении.
• NPM_CONFIG_CACHE: опционально. Путь для кеша npm или pnpm. Если разместить его во временной папке ServBay (/Applications/ServBay/tmp/npm/cache), это упростит управление и не будет засорять основную систему.

Сохраните и закройте файл .servbay.config.

Шаг 2: Проверьте выбранную версию в терминале ServBay

1. Откройте главное окно приложения ServBay.

2. Перейдите в раздел «Терминал» (Terminal), чтобы запустить интегрированный терминал ServBay.

3. С помощью команды cd перейдите в каталог вашего проекта:

   cd /Applications/ServBay/www/your-project-name

   (Замените /Applications/ServBay/www/your-project-name на фактический путь к проекту)

4. Выполните команду node -v, чтобы проверить используемую версию Node.js:

   node -v

   Вы увидите вывод с версией, заданной в .servbay.config (например, v20.x.x).

5. Дополнительно можно проверить версии пакетных менеджеров через npm -v, pnpm -v или yarn -v — они будут связаны с активной версией Node.js.

Теперь любые команды Node.js, npm/pnpm/yarn, запускаемые в этом каталоге, будут использовать версию согласно .servbay.config.

Практический пример

Посмотрим, как .servbay.config обеспечивает автоматическую смену Node.js между разными проектами.

Допустим, у вас есть два проекта: для project-a нужен Node.js v18, для project-b — Node.js v20.

1. Создание директорий и конфигурационных файлов:

   # Создаём примеры проектов в каталоге www ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Для project-a создаём .servbay.config c Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Для project-b — с Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Проверка переключений в терминале:

   Откройте терминал ServBay и выполните:

   # Перейти в project-a
   cd /Applications/ServBay/www/project-a
   # Проверить версию Node.js
   node -v
   # Ожидаемый результат: v18.x.x
   
   # Перейти в project-b
   cd ../project-b
   # Проверить версию Node.js
   node -v
   # Ожидаемый результат: v20.x.x
   
   # Вернуться в project-a
   cd ../project-a
   # Проверить версию Node.js
   node -v
   # Ожидаемый результат: v18.x.x

Как видно, ServBay определяет вашу текущую директорию и мгновенно загружает указанную в .servbay.config версию Node.js для каждого проекта.

Ниже показано, как при переходах между проектами версия Node.js меняется автоматически по содержимому .servbay.config (рисунок демонстрационный, внешний вид приложения может отличаться):

Важные нюансы

• Файл .servbay.config должен находиться в директории проекта или одном из её родительских каталогов. ServBay ищет ближайший вверх по структуре каталогов файл.
• Работайте только в терминале ServBay или внешнем терминале с корректно настроенными переменными окружения от ServBay.
• Убедитесь, что версия, указанная в NODE_VERSION, действительно установлена и активирована в ServBay. Иначе программа либо вернётся к версии по умолчанию, либо команда Node.js окажется недоступной.
• Настройки из .servbay.config действуют ТОЛЬКО на текущую сессию терминала и её потомки, не затрагивая глобальную систему или процессы вне среды ServBay.

Часто задаваемые вопросы (FAQ)

В: Что если в каталоге проекта нет файла .servbay.config?

О: В таком случае ServBay ищет этот файл в родительских директориях. Если нигде не нашёл, используется глобальная настройка или версия Node.js по умолчанию (как правило, в ServBay отмечена как «Default»).

В: Как узнать, какие версии Node.js поддерживает ServBay?

О: Откройте приложение ServBay, перейдите в меню «Пакеты» (Packages) — слева находится список всех установленных и доступных пакетов, в том числе и разных версий Node.js. Можно включать или выключать их по необходимости.

В: Может ли .servbay.config изменить систему или повлиять на другие приложения?

О: Нет, конфигурация из .servbay.config действует только для текущей терминальной сессии ServBay и приложений, запущенных из неё. Переменные окружения системы не меняются — это один из ключевых моментов реализации изоляции проектов.

В: Можно ли через .servbay.config управлять и другими настройками ServBay?

О: Да! .servbay.config — универсальное средство задания переменных окружения на уровне проекта. Помимо Node.js, вы можете настраивать и другие переменные, которые будут доступны всем процессам в данном каталоге ServBay. Список поддерживаемых опций может меняться с обновлениями программы, но основная возможность — задание переменных окружения.

Заключение

Используя файл .servbay.config в ServBay, вы легко и эффективно можете выставлять и управлять отдельной версией Node.js для каждого вашего локального проекта. Это значительно проще и быстрее, чем традиционные менеджеры версий или контейнеризация, а полноценная интеграция с системой разработки ServBay помогает строить более устойчивый, чистый и командо-ориентированный рабочий процесс. Примените .servbay.config в своих проектах уже сегодня и ощутите удобство, которое дарит ServBay!