下载与安装
本页将引导你完成 Elftia 的下载、安装和首次启动。
系统要求
在安装前，请确认你的设备满足以下最低要求：
| 平台 | 最低版本 | 架构 |
|---|---|---|
| Windows | Windows 10 (64-bit) 或更高 | x64 / arm64 |
| macOS | macOS 10.15 (Catalina) 或更高 | Intel / Apple Silicon |
| Linux | Ubuntu 20.04 / Fedora 36 / Debian 11 或同等发行版 | x64 |
硬件建议：
- 内存：4 GB 以上（推荐 8 GB）
- 磁盘空间：至少 500 MB 可用空间
- 网络：需要互联网连接才能调用 LLM API
可选依赖（Agent 功能需要）：
Elftia 会在首次启动时自动检测以下工具。如果你计划使用 Agent 功能（代码编辑、文件操作、Shell 命令等），建议提前安装：
| 工具 | 用途 | 下载地址 |
|---|---|---|
| Node.js 18+ | MCP 服务器运行时、部分工具执行 | nodejs.org |
| Git | 版本控制、项目管理 | git-scm.com |
| uv / uvx | Python 包管理（部分 MCP 服务器需要） | astral.sh/uv |
这些依赖不是必须的——如果你只需要基本的 AI 聊天功能，可以跳过。
下载
官方网站
前往 Elftia 官方网站下载页面，选择适合你操作系统的版本。
GitHub Releases
你也可以从 GitHub Releases 页面下载最新版本或历史版本。每个 Release 包含以下安装包：
| 平台 | 安装包格式 | 文件名示例 |
|---|---|---|
| Windows | NSIS 安装程序 | Elftia-Setup-x.x.x.exe |
| macOS | DMG 镜像 | Elftia-x.x.x.dmg / Elftia-x.x.x-arm64.dmg |
| Linux | AppImage | Elftia-x.x.x.AppImage |
安装步骤
Windows
- 双击下载的
Elftia-Setup-x.x.x.exe文件。 - 如果出现 Windows SmartScreen 提示，点击「更多信息」然后选择「仍要运行」。
- 选择安装路径（默认为
C:\Users\<用户名>\AppData\Local\Elftia）。 - 等待安装完成，安装程序会自动创建桌面快捷方式和开始菜单项。
- 点击「完成」启动 Elftia。
Elftia 使用 NSIS 安装程序，支持自动更新。安装后的程序可以在系统设置中正常卸载。
macOS
- 双击下载的
.dmg文件挂载磁盘映像。 - 在弹出的窗口中，将 Elftia 图标拖入「Applications」文件夹。
- 首次打开时，macOS 可能提示「无法验证开发者」：
- 打开「系统偏好设置 → 安全性与隐私 → 通用」
- 点击「仍要打开」按钮
- Elftia 启动后即可使用。
Apple Silicon (M1/M2/M3/M4) 用户请下载 arm64 版本以获得最佳性能。Intel Mac 用户下载标准版本。
Linux
- 下载
.AppImage文件。 - 赋予执行权限：
chmod +x Elftia-x.x.x.AppImage
- 双击运行或在终端中执行：
./Elftia-x.x.x.AppImage
如果 AppImage 无法运行，可能需要安装 FUSE：sudo apt install libfuse2（Ubuntu/Debian）。
首次启动
首次启动 Elftia 时，你会看到以下流程：
1. 环境检测
Elftia 会自动检测系统中已安装的工具（Node.js、Git、ripgrep、uv/uvx 等）。检测结果会显示在设置页面的「环境」区域中，每个工具旁边会显示绿色（已安装）或红色（未安装）的状态标识。
你可以稍后在 设置 → 通用 → 环境 中查看和管理这些工具。部分未安装的工具可以直接点击「安装」按钮自动安装。
2. 语言选择
Elftia 支持三种界面语言：
- 简体中文
- English
- 日本語
默认语言根据系统语言自动选择，你可以在 设置 → 通用 → 语言 中随时更改。
3. 配置 LLM 提供商
要开始使用 AI 聊天功能，你需要至少配置一个 LLM 提供商。详见 第一次对话。
Steam 版本差异
如果你通过 Steam 安装 Elftia，请注意以下不同之处：
| 对比项 | 标准版 | Steam 版 |
|---|---|---|
| 更新方式 | 应用内自动更新（electron-updater） | 通过 Steam 客户端更新 |
| 安装路径 | 用户自定义 | Steam 库文件夹 |
| 卸载方式 | 系统设置 / 控制面板 | 通过 Steam 卸载 |
| 功能 | 完全相同 | 完全相同 |
Steam 版本的功能与标准版完全一致，仅更新机制不同。
常见安装问题
安装程序无法运行
Windows： 检查是否被杀毒软件拦截。部分杀毒软件可能误报 Electron 应用。将 Elftia 添加到杀毒软件的白名单中。
macOS： 如果出现「已损坏，无法打开」的提示，在终端运行：
xattr -cr /Applications/Elftia.app
Linux： 确认已安装 FUSE 依赖，并且文件有执行权限。
启动时白屏或闪退
- 确认显卡驱动已更新到最新版本。
- 尝试以管理员权限运行（Windows）。
- 检查是否有其他 Elftia 实例正在运行，关闭后重试。
- 如果使用的是较旧的 GPU，尝试启动时添加
--disable-gpu参数。
缺少 .NET 或 Visual C++ 运行时（Windows）
部分 Windows 系统可能缺少必要的运行时。安装 Visual C++ Redistributable 后重试。
防火墙阻止联网
Elftia 需要访问互联网来调用 LLM API。确保防火墙允许 Elftia 的出站连接。如需使用代理，请参考 使用代理。
安装完成后，继续阅读 第一次对话 来开始你的 AI 之旅。