• Русский

      • Настройка локального окружения разработки на Windows с WSL

      Для локальной разработки NocoBase на Windows рекомендуем сначала подготовить WSL 2. Это позволяет Node.js, Yarn, NocoBase CLI, командам Docker и ИИ агентам работать в одной оболочке Linux — с путями, правами и сборкой нативных зависимостей, ближе к типичным Linux-окружениям развёртывания.

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

      Перед началом

      Перед установкой WSL проверьте версию Windows и состояние виртуализации.

      Проверка версии Windows

      Нажмите Win + R, введите winver и убедитесь, что ваша система соответствует одному из следующих требований:

      • Windows 11
      • Windows 10 версии 2004 или новее, сборка 19041 или новее

      Если версия старше, обновите Windows перед продолжением.

      Проверка виртуализации

      Откройте диспетчер задач, перейдите в раздел «Производительность» / «ЦП» и убедитесь, что виртуализация отображается как «Включено».

      Если виртуализация не включена, включите её в BIOS / UEFI. Название опции зависит от производителя, например Intel VT-x, Intel Virtualization Technology, AMD-V или SVM Mode.

      Шаг 1: Установка WSL 2

      Откройте PowerShell от имени администратора:

      1. Откройте меню «Пуск» Windows
      2. Найдите PowerShell
      3. Щёлкните правой кнопкой мыши и выберите «Запуск от имени администратора»

      Выполните:

      wsl --install

      После установки перезагрузите компьютер. По умолчанию эта команда устанавливает Ubuntu. При первом запуске Ubuntu попросит создать имя пользователя и пароль Linux. Эти имя и пароль используются только внутри WSL и не обязаны совпадать с учётной записью Windows.

      Чтобы установить конкретный дистрибутив, сначала выведите список доступных дистрибутивов:

      wsl --list --online

      Затем установите дистрибутив, например Ubuntu:

      wsl --install -d Ubuntu

      Шаг 2: подтвердите версию WSL

      В PowerShell выполните:

      wsl --list --verbose

      Убедитесь, что у нужного дистрибутива указано VERSION 2:

        NAME      STATE           VERSION
* Ubuntu    Running         2

      Если это WSL 1, преобразуйте его в WSL 2 и сделайте WSL 2 версией по умолчанию:

      wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --update

      Шаг 3: установите Docker Desktop

      Если вы планируете устанавливать или запускать NocoBase через Docker, установите Docker Desktop для Windows.

      Для локальной разработки обычно достаточно режима Per-user. На странице настройки выберите Use WSL 2 instead of Hyper-V, затем запустите Docker Desktop из меню Пуск.

      Шаг 4: включите интеграцию Docker с WSL

      В Docker Desktop включите backend WSL 2:

      1. Docker Desktop / Settings / General
      2. Use the WSL 2 based engine
      3. Apply

      Docker Desktop WSL 2 engine

      Затем включите интеграцию с WSL-дистрибутивом:

      1. Docker Desktop / Settings / Resources / WSL Integration
      2. Enable integration with my default WSL distro
      3. Включите нужный дистрибутив, например Ubuntu
      4. Apply & restart или Apply

      Docker Desktop WSL integration

      Если WSL Integration не отображается, Docker Desktop, скорее всего, находится в режиме Windows containers. Переключитесь на Linux containers через значок Docker в системном трее Windows и проверьте снова.

      Шаг 5: проверьте Docker

      Сначала проверьте из PowerShell:

      wsl --list --verbose
docker version
docker compose version
docker run hello-world

      Зайдите в WSL:

      wsl

      Затем выполните внутри WSL:

      docker version
docker compose version
docker run hello-world

      Если контейнер hello-world скачивается и запускается успешно, интеграция Docker Desktop и WSL 2 работает.

      Шаг 6: установите Node.js и Yarn в WSL

      WSL не является средой Node.js по умолчанию. Ubuntu, установленная через wsl --install, обычно не содержит Node.js и npm.

      В WSL сначала проверьте:

      node -v
npm -v

      Если команда не найдена, установите Node.js 22 через NodeSource:

      sudo apt update
sudo apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs
node -v
npm -v
npx -v

      Если нужно переключать версии Node.js между проектами, используйте nvm:

      sudo apt update
sudo apt install -y curl ca-certificates
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.5/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node -v
npm -v
npx -v
      Примечание

      Выберите NodeSource или nvm. Не рекомендуется смешивать оба способа управления Node.js в одном пользователе WSL.

      Установите Yarn 1.x:

      corepack enable
corepack prepare yarn@1.22.22 --activate
yarn -v

      Если Corepack недоступен:

      npm install -g yarn@1.22.22
yarn -v

      Шаг 7: установите Codex CLI

      Codex CLI также можно использовать в нативной командной строке Windows. В этом руководстве он устанавливается в WSL, чтобы Codex и локальный инструментарий NocoBase находились в одной Linux-среде.

      Убедитесь, что вы находитесь в WSL:

      echo $WSL_DISTRO_NAME

      Установите Codex CLI в WSL:

      curl -fsSL https://chatgpt.com/codex/install.sh | sh

      Для неинтерактивной установки:

      curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

      Запустите и проверьте Codex:

      codex
codex --version

      Рекомендуется запускать Codex из каталога проекта внутри WSL:

      mkdir -p ~/projects
cd ~/projects/my-app
codex
      Примечание

      Поскольку Codex установлен в WSL, затем запускайте codex из терминала WSL. PowerShell использует нативную среду Windows, а не WSL-среду, подготовленную в этом руководстве.

      Где хранить файлы проекта

      Рекомендуется хранить проекты в файловой системе WSL:

      ~/projects/my-app

      Не используйте путь Windows mount как место по умолчанию:

      /mnt/c/Users/<your-name>/projects/my-app

      Обычно это дает лучшую производительность файловой системы и снижает проблемы с правами и символическими ссылками.

      Чтобы открыть файлы WSL из Проводника Windows:

      \\wsl$\Ubuntu\home\<your-name>

      FAQ

      WSL не находит команду docker

      Убедитесь, что дистрибутив использует WSL 2, затем включите интеграцию в Docker Desktop / Settings / Resources / WSL Integration.

      wsl --list --verbose
wsl --set-version Ubuntu 2

      WSL Integration не отображается

      Docker Desktop, вероятно, находится в режиме Windows containers. Через значок Docker переключитесь на Linux containers и снова откройте настройки WSL Integration.

      Docker Desktop не запускается или WSL выглядит некорректно

      Сначала попробуйте:

      wsl --shutdown
wsl --update

      Затем перезапустите Docker Desktop.

      Docker Engine уже установлен вручную в WSL

      Docker рекомендует удалить Docker Engine или Docker CLI, установленные напрямую в WSL-дистрибутиве, перед использованием Docker Desktop, чтобы избежать конфликтов с WSL-интеграцией.

      WSL не находит команду codex

      Убедитесь, что вы в WSL, затем проверьте PATH:

      echo $WSL_DISTRO_NAME
which codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh

      Официальные материалы