EzVibeR/docs/usage/01-系统要求与依赖.md

01 · 系统要求与依赖

1. 跨平台支持一览

平台	是否支持	备注
Linux (X11)	✅ 主推	默认 GDK_BACKEND=x11 强制走 XWayland
Linux (Wayland / GNOME)	⚠️ 部分	桌宠的"始终置顶"和"所有工作区可见"会失效（已知 bug）
Linux (Wayland / KDE)	⚠️ 部分	同上
macOS (Intel / Apple Silicon)	✅	截图走系统能力；首次启动需要授权辅助功能/屏幕录制
Windows 10/11	✅	WebView2 已内嵌，理论无外部依赖

2. 三平台共同需要

依赖	最低版本	用途
Node.js	18+	构建前端
npm	9+	包管理
Rust	1.65+	编译后端
Cargo	随 Rust 一起	Rust 构建
C/C++ 工具链	—	Rust 编译需要（Linux: gcc / Windows: MSVC / macOS: Xcode CLT）

💡 Rust 推荐通过 rustup 安装；Node 推荐通过 nvm 或 fnm 安装。

3. 各平台额外的系统库

🐧 Linux（Debian / Ubuntu / Fedora / Arch）

Debian / Ubuntu：

sudo apt update
sudo apt install -y \
  build-essential curl wget file libssl-dev \
  libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev \
  libwebkit2gtk-4.1-dev libsoup-3.0-dev \
  libdbus-1-dev pkg-config \
  imagemagick libnotify-bin

Fedora（项目开发环境）：

sudo dnf install -y \
  gcc gcc-c++ make \
  gtk3-devel libappindicator-gtk3-devel librsvg2-devel \
  webkit2gtk4.1-devel libsoup3-devel \
  dbus-devel pkgconf-pkg-config \
  ImageMagick libnotify

Arch / Manjaro：

sudo pacman -S --needed \
  base-devel \
  gtk3 libappindicator-gtk3 librsvg \
  webkit2gtk-4.1 libsoup3 \
  dbus \
  imagemagick libnotify

说明：

• libappindicator / libayatana-appindicator3 — 系统托盘图标
• webkit2gtk-4.1 — Tauri 在 Linux 的渲染后端（必须是 4.1，不要装 4.0）
• imagemagick — 提供 convert 命令，作为截图兜底（首选是 xdg-desktop-portal）
• libnotify / libnotify-bin — 提供 notify-send 命令，用于发送系统通知
• xdg-desktop-portal — 截图首选方式。Fedora 41+ / Ubuntu 22+ 默认已装，首次截图会弹授权对话框，授权后永久通过

🍎 macOS

依赖	用途
Xcode Command Line Tools	C/C++ 编译
rustup 装的 Rust	后端编译
（可选）iTerm2 / Terminal	看日志
（可选）xcodegen	一般不需要

首次截图 macOS 会弹"屏幕录制"权限请求，到 系统设置 → 隐私与安全性 → 屏幕录制 给 EzVibeR+ 授权。

🪟 Windows

依赖	说明
Microsoft C++ 生成工具（MSVC）	下载，安装时勾选"使用 C++ 的桌面开发"
WebView2 Runtime	Win11 已自带；Win10 可能需要，安装包内嵌
Git for Windows（可选）	拉代码用

4. 网络要求

用途	是否需要	备注
加载本地 Live2D 模型	否	模型目录全在本地
加载网络 Live2D 模型	是	走你填的 URL
LLM 对话	是	走你配的 API（OpenAI/Anthropic 或自部署网关）
系统通知	否	本地发
自动更新检查	是	默认启用，可在配置里关

5. 硬件要求

项	最低	推荐
CPU	双核 1.5GHz	四核+
内存	2 GB	4 GB+
硬盘	500 MB（不含模型）	2 GB+（含模型和会话）
显卡	任意	集成显卡也能跑，Live2D 走 WebGL

💡 你的 Live2D 模型文件不包含在软件里，需要自己提供。常见模型来源：Live2D Cubism Samples / 模之屋 等。一个普通模型 30-100 MB，复杂模型 200+ MB。

6. 端口

• Tauri 后端在 tauri:// 内部协议
• 内嵌 axum 服务随机监听 1024-65535 之间的一个端口（启动时探测可用），用于给前端 webview 提供本地 Live2D 模型文件
• 不需要用户开放任何入站端口

---

下一步：02-安装与运行.md