常见问题
安装遇到问题？这里有故障排查、预编译文件下载和手动救援方案
安装故障排查
npm install 报错：原生模块编译失败
安装过程中需要编译原生模块（终端仿真、记忆持久化、图像处理）。如果缺少编译工具链，会报错。
Linux：安装编译工具链
sudo apt install -y build-essential python3macOS：安装 Xcode Command Line Tools
xcode-select --installWindows：安装 Visual C++ Build Tools，勾选 "C++ 桌面开发" 工作负载。
Linux x64 CPU 环境下语义搜索模块安装失败
语义搜索模块在纯 CPU 环境下可能需要手动配置。安装脚本通常会自动处理，如果失败可设置环境变量跳过：
ONNXRUNTIME_NODE_INSTALL=skip npm install -g @eva/cli跳过后语义搜索功能将不可用，但不影响其他所有功能。
安装后执行 eva 提示 command not found
这是 Linux/WSL 下文件权限问题。手动添加执行权限：
chmod +x $(which eva)直接下载预编译文件（免编译）
当编译环境缺失或 GitHub 联通性差时，可以直接下载预编译文件跳过编译步骤。
第一步：确认你的 ABI 版本
node -p "process.versions.modules"| Node.js 版本 | ABI 版本 |
|---|---|
| Node.js 18 | v108 |
| Node.js 20 | v115 |
| Node.js 22 | v127 |
第二步：下载对应文件
根据你的操作系统和 ABI 版本，下载对应的预编译包：
macOS x64 (Intel)
macOS arm64 (Apple Silicon)
Windows x64
如果 GitHub 无法访问，可使用代理：export https_proxy=http://你的代理地址:端口
手动救援步骤
当 npm install 失败后，按以下步骤手动修复：
# 1. 先正常安装（忽略编译错误）
npm install -g @eva/cli 2>/dev/null || true
# 2. 找到安装位置
EVA_PATH=$(npm root -g)/@eva/cli
echo $EVA_PATH
# 3. 下载预编译文件（以 Node 20 / linux-x64 为例）
cd /tmp
wget https://github.com/WiseLibs/better-sqlite3/releases/download/v12.9.0/better-sqlite3-v12.9.0-node-v115-linux-x64.tar.gz
# 4. 解压并替换
tar xzf better-sqlite3-v12.9.0-node-v115-linux-x64.tar.gz
mkdir -p "$EVA_PATH/node_modules/better-sqlite3/build/Release"
cp build/Release/better_sqlite3.node "$EVA_PATH/node_modules/better-sqlite3/build/Release/"
# 5. 验证
eva --version如果 wget 也无法访问 GitHub，可尝试使用 curl --proxy http://你的代理:端口 -L -o 替代。
还有问题？加入 QQ 群
扫描左侧二维码加入 EVA 用户交流群，获取社区支持和实时帮助。
群内提供：安装指导、使用答疑、功能建议、Bug 反馈
