本地开发
本指南帮助你快速搭建 Elftia 本地开发环境并开始编码。
前提条件
Node.js
项目要求 Node.js v24（参见项目根目录 .nvmrc）。推荐使用 nvm 或 fnm 管理版本：
nvm install
nvm use
原生构建工具
项目依赖 better-sqlite3 等原生 Node.js 模块，需要 C/C++ 编译环境：
| 平台 | 所需工具 | 安装方式 |
|---|---|---|
| Windows | Visual Studio Build Tools 2022 | npm install -g windows-build-tools 或从 VS 官网 安装 |
| macOS | Xcode Command Line Tools | xcode-select --install |
| Linux | build-essential, python3 | sudo apt install build-essential python3 (Debian/Ubuntu) |
其他依赖
- Git >= 2.30
- ripgrep (rg) —
postinstall脚本会自动下载，也可手动安装
初始化项目
# 1. 克隆仓库
git clone <repo-url> elftia
cd elftia
# 2. 安装依赖
npm install
npm install 的 postinstall 脚本会自动：
- 重新编译原生模块（
better-sqlite3、node-pty等）以匹配当前 Electron 版本 - 下载平台对应的
ripgrep二进制文件
# 3. 创建环境变量文件
cp .env.example .env
根据需要编辑 .env，填写 API Key 等配置。
启动开发模式
npm run dev
这会启动 electron-vite dev，同时监听三个目标的代码变更：
| 目标 | 目录 | 热重载 |
|---|---|---|
| Main Process | packages/desktop/app/main/ | 重启主进程 |
| Preload Script | packages/desktop/app/preload/ | 重启主进程 |
| Renderer | packages/renderer/src/ | Vite HMR（端口 5375） |
tip
首次启动时如果遇到原生模块错误，尝试运行 npm run rebuild 重新编译。
所有开发命令
| 命令 | 说明 |
|---|---|
npm run dev | 启动 Electron + Vite 开发模式（main + preload + renderer） |
npm run dev:web | 仅启动 Renderer（Web 模式，无 Electron） |
npm run dev:server | 启动 Fastify Web 服务端（可选） |
npm run build | 构建所有包（renderer + desktop） |
npm run build:renderer | 仅构建前端（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 分类统计） |
调试
主进程调试
方法一：--inspect 标志
# 在 package.json 的 dev 脚本中添加 --inspect
# 或直接运行：
electron --inspect=9229 .
然后在 Chrome 中访问 chrome://inspect，连接到主进程。
方法二：VS Code
在 .vscode/launch.json 中添加以下配置：
{
"type": "node",
"request": "attach",
"name": "Attach to Main Process",
"port": 9229,
"skipFiles": ["<node_internals>/**"]
}
渲染进程调试
按 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/ |
开发 vs 生产差异
| 方面 | 开发模式 | 生产模式 |
|---|---|---|
| 前端服务 | Vite Dev Server (HMR) | 静态文件（file://） |
| 源码映射 | 开启 | 关闭 |
| 压缩 | 无 | Terser（移除 console.log） |
| 代码分割 | 全量加载 | React.lazy 按路由分割 |
| CSP | 宽松 | 严格 |
| DevTools | 自动打开 | 默认隐藏（开发者模式可启用） |
| 数据库 | 开发用户数据目录 | 正式用户数据目录 |
| 日志级别 | debug | info |
Worker 线程
Elftia 在主进程中启动多个 Worker 线程以避免阻塞 IPC：
| Worker | 文件 | 职责 |
|---|---|---|
db.worker | workers/db/ | SQLite 读写操作 |
fileSearch.worker | workers/fileSearch/ | 文件内容搜索（ripgrep） |
fileWatcher.worker | workers/fileWatcher/ | 文件系统变更监听 |
mcp.worker | workers/mcp/ | MCP 服务器通信 |
diagnostics.worker | workers/diagnostics/ | 系统诊断信息收集 |
project.worker | workers/project/ | 项目目录索引 |
开发模式下，Worker 使用 ts-node 直接运行 TypeScript 源码；生产模式下，Worker 被 tsup 编译为独立 JS 文件。
常见问题
原生模块编译失败
# 清理并重新安装
rm -rf node_modules
npm install
# 或仅重新编译原生模块
npm run rebuild
端口被占用
Vite Dev Server 默认使用端口 5375。如果被占用：
# 查找占用进程
lsof -i :5375 # macOS/Linux
netstat -ano | findstr :5375 # Windows
数据库锁定
如果出现 "database is locked" 错误，确保没有多个 Elftia 实例在运行。开发时可使用诊断功能导出数据库状态：
window.api.diagnostics.dump()