Перейти к основному содержимому

Локальная разработка

Это руководство поможет быстро настроить локальное окружение разработки Elftia и начать писать код.

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

Node.js​

Проекту требуется Node.js v24 (см. .nvmrc в корне проекта). Рекомендуем использовать nvm или fnm для управления версиями:

nvm install
nvm use

Нативные инструменты сборки​

Проект зависит от нативных модулей Node.js, таких как better-sqlite3, которым требуется окружение компиляции C/C++:

ПлатформаНеобходимые инструментыУстановка
WindowsVisual Studio Build Tools 2022npm install -g windows-build-tools или установка с сайта VS
macOSXcode Command Line Toolsxcode-select --install
Linuxbuild-essential, python3sudo apt install build-essential python3 (Debian/Ubuntu)

Другие зависимости​

  • Git >= 2.30
  • ripgrep (rg) — автоматически скачивается скриптом postinstall либо устанавливается вручную

Инициализация проекта​

# 1. Clone the repository
git clone <repo-url> elftia
cd elftia

# 2. Install dependencies
npm install

Скрипт postinstall, запускаемый командой npm install, автоматически:

  • Перекомпилирует нативные модули (better-sqlite3, node-pty и т. д.) под текущую версию Electron
  • Скачивает бинарный файл ripgrep для вашей платформы
# 3. Create the environment variable file
cp .env.example .env

При необходимости отредактируйте .env, чтобы указать API-ключи и другую конфигурацию.


Запуск режима разработки​

npm run dev

Эта команда запускает electron-vite dev, одновременно отслеживая изменения кода в трех целях:

ЦельКаталогГорячая перезагрузка
Основной процессpackages/desktop/app/main/Перезапускает основной процесс
Скрипт preloadpackages/desktop/app/preload/Перезапускает основной процесс
Rendererpackages/renderer/src/Vite HMR (порт 5375)
подсказка

Если при первом запуске возникают ошибки нативных модулей, попробуйте выполнить npm run rebuild, чтобы перекомпилировать их.


Все команды разработки​

КомандаОписание
npm run devЗапустить режим разработки Electron + Vite (main + preload + renderer)
npm run dev:webЗапустить только Renderer (веб-режим, без Electron)
npm run dev:serverЗапустить веб-сервер Fastify (опционально)
npm run buildСобрать все пакеты (renderer + desktop)
npm run build:rendererСобрать только фронтенд (production-режим Vite)
npm run build:desktopСобрать только основной процесс Electron (tsup)
npm run build:officialСобрать официальный релиз (с подписью)
npm run build:steamСобрать версию Steam
npm run lintЗапустить ESLint + проверку типов TypeScript
npm run lint:eslintЗапустить только ESLint
npm run typecheckЗапустить только проверку компиляции TypeScript
npm run testЗапустить тесты Vitest
npm run formatОтформатировать весь код через Prettier
npm run format:file <path>Отформатировать один файл через Prettier
npm run verify:buildПроверить размер артефакта сборки (4 ключевые метрики)
npm run analyze:buildПроанализировать состав bundle (статистика chunk)

Отладка​

Отладка основного процесса​

Способ 1: флаг --inspect​

# Add --inspect to the dev script in package.json
# Or run directly:
electron --inspect=9229 .

Затем откройте chrome://inspect в Chrome и подключитесь к основному процессу.

Способ 2: VS Code​

Добавьте следующую конфигурацию в .vscode/launch.json:

{
"type": "node",
"request": "attach",
"name": "Attach to Main Process",
"port": 9229,
"skipFiles": ["<node_internals>/**"]
}

Отладка процесса Renderer​

Нажмите Ctrl+Shift+I (Windows/Linux) или Cmd+Option+I (macOS), чтобы открыть DevTools.

DevTools поддерживает:

  • React DevTools — автоматически загружается после установки соответствующего расширения браузера
  • Network — мониторинг вызовов IPC (они отображаются как запросы invoke)
  • Performance — анализ производительности рендеринга

Логирование​

Elftia использует Winston для управления логами.

Переменная окруженияОписаниеПо умолчанию
LOG_LEVELУровень логирования (debug / info / warn / error)info

Расположения файлов логов:

ПлатформаПуть
Windows%APPDATA%/elftia/logs/
macOS~/Library/Application Support/elftia/logs/
Linux~/.config/elftia/logs/

Различия между разработкой и production​

АспектРежим разработкиProduction-режим
Раздача фронтендаVite Dev Server (HMR)Статические файлы (file://)
Source mapsВключеныОтключены
МинификацияНетTerser (удаляет console.log)
Разделение кодаПолная загрузкаReact.lazy по маршрутам
CSPОслабленнаяСтрогая
DevToolsОткрывается автоматическиПо умолчанию скрыт (можно включить в режиме разработчика)
База данныхКаталог пользовательских данных для разработкиКаталог пользовательских данных для production
Уровень логированияdebuginfo

Worker Threads​

Elftia запускает несколько Worker threads в основном процессе, чтобы не блокировать IPC:

WorkerФайлОтветственность
db.workerworkers/db/Операции чтения/записи SQLite
fileSearch.workerworkers/fileSearch/Поиск по содержимому файлов (ripgrep)
fileWatcher.workerworkers/fileWatcher/Мониторинг изменений файловой системы
mcp.workerworkers/mcp/Взаимодействие с MCP-сервером
diagnostics.workerworkers/diagnostics/Сбор системной диагностики
project.workerworkers/project/Индексация каталогов проекта

В режиме разработки worker запускают исходный TypeScript напрямую через ts-node; в production-режиме worker компилируются tsup в самостоятельные JS-файлы.


Распространенные проблемы​

Ошибка компиляции нативного модуля​

# Clean and reinstall
rm -rf node_modules
npm install

# Or recompile native modules only
npm run rebuild

Порт уже используется​

Vite Dev Server по умолчанию использует порт 5375. Если он занят:

# Find the process using the port
lsof -i :5375 # macOS/Linux
netstat -ano | findstr :5375 # Windows

База данных заблокирована​

Если вы видите ошибку "database is locked", убедитесь, что запущен не более чем один экземпляр Elftia. В режиме разработки можно экспортировать состояние базы данных через diagnostics API:

window.api.diagnostics.dump()