Skip to main content

下载与安装

本页将引导你完成 Elftia 的下载、安装和首次启动。

系统要求​

在安装前，请确认你的设备满足以下最低要求：

平台最低版本架构
WindowsWindows 10 (64-bit) 或更高x64 / arm64
macOSmacOS 10.15 (Catalina) 或更高Intel / Apple Silicon
LinuxUbuntu 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 / uvxPython 包管理（部分 MCP 服务器需要）astral.sh/uv

这些依赖不是必须的——如果你只需要基本的 AI 聊天功能，可以跳过。

下载​

官方网站​

前往 Elftia 官方网站下载页面，选择适合你操作系统的版本。

GitHub Releases​

你也可以从 GitHub Releases 页面下载最新版本或历史版本。每个 Release 包含以下安装包：

平台安装包格式文件名示例
WindowsNSIS 安装程序Elftia-Setup-x.x.x.exe
macOSDMG 镜像Elftia-x.x.x.dmg / Elftia-x.x.x-arm64.dmg
LinuxAppImageElftia-x.x.x.AppImage

安装步骤​

Windows​

  1. 双击下载的 Elftia-Setup-x.x.x.exe 文件。
  2. 如果出现 Windows SmartScreen 提示，点击「更多信息」然后选择「仍要运行」。
  3. 选择安装路径（默认为 C:\Users\<用户名>\AppData\Local\Elftia）。
  4. 等待安装完成，安装程序会自动创建桌面快捷方式和开始菜单项。
  5. 点击「完成」启动 Elftia。
tip

Elftia 使用 NSIS 安装程序，支持自动更新。安装后的程序可以在系统设置中正常卸载。

macOS​

  1. 双击下载的 .dmg 文件挂载磁盘映像。
  2. 在弹出的窗口中，将 Elftia 图标拖入「Applications」文件夹。
  3. 首次打开时，macOS 可能提示「无法验证开发者」：
    • 打开「系统偏好设置 → 安全性与隐私 → 通用」
    • 点击「仍要打开」按钮
  4. Elftia 启动后即可使用。
tip

Apple Silicon (M1/M2/M3/M4) 用户请下载 arm64 版本以获得最佳性能。Intel Mac 用户下载标准版本。

Linux​

  1. 下载 .AppImage 文件。
  2. 赋予执行权限： 
    chmod +x Elftia-x.x.x.AppImage
  3. 双击运行或在终端中执行： 
    ./Elftia-x.x.x.AppImage
tip

如果 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 之旅。