02 · 安装与运行

最快跑起来（开发模式）

适合：第一次跑通、边改边看效果、调 UI。

# 1. 拉代码
cd /path/to/EzVibeR+

# 2. 装前端依赖（首次需要 1-3 分钟）
npm install

# 3. 一键启动：Vite dev server + Tauri + Rust 后端全开
npm run tauri:dev

第一次 npm run tauri:dev 会下载很多 Rust crate（依赖 tokio、axum、rusqlite、image、reqwest、zbus、ashpd 等），可能 5-15 分钟。之后增量编译快很多。

启动成功后你会看到：

主窗口（桌宠）：透明窗口里出现 Live2D 模型
聊天面板：在桌宠窗口右侧
系统托盘：右下角多了一个小图标

没有 Live2D 模型？ 软件启动后不会自动报错，只是会显示一个空白区域或者内置的占位资源（取决于 model_dir 配置）。第一次使用请先到 03-首次启动配置.md 设置模型目录。

三平台的生产构建

一条命令搞定当前平台

# 完整打包（前端类型检查 + 前端 build + Rust release build + 打包安装包）
npm run tauri build

打包产物的位置：

Linux：src-tauri/target/release/bundle/{deb,appimage,rpm}/
macOS：src-tauri/target/release/bundle/{dmg,app}/
Windows：src-tauri/target/release/bundle/{msi,nsis}/

macOS 默认会同时出 .dmg 和 .app，Windows 默认同时出 .msi 和 .exe（NSIS），Linux 默认出 .deb（Debian/Ubuntu）和 .AppImage（通用）。具体出什么取决于你的系统——Tauri 当前是按当前构建平台自动选择 targets。

各平台分步构建（可选）

# 1) 只构建前端（产出 dist/）
npm run build

# 2) 只构建后端（产出 src-tauri/target/release/live2d）
cd src-tauri
cargo build --release
cd ..

# 3) 直接运行编译后的二进制
./src-tauri/target/release/live2d        # Linux/macOS
src-tauri\target\release\live2d.exe      # Windows

生产构建出来的二进制就是「桌宠可执行文件」——直接双击即可运行，不需要再装 Node、npm 之类。

跨平台交叉打包（可选，需要较强配置）

目标平台	需要的额外工具	命令
macOS (.app / .dmg)	macOS + Xcode CLT	在 macOS 上 `npm run tauri build`
Windows (.msi / .exe)	Windows + MSVC	在 Windows 上 `npm run tauri build`
Linux (.deb / .AppImage)	Linux	在 Linux 上 `npm run tauri build`

💡 Tauri 不太鼓励跨平台交叉编译（尤其 macOS → Windows / Linux → macOS），因为要模拟整个 WebView 栈。最稳的做法是在目标平台上直接构建。

启动时环境变量

变量	值	作用
`EZVIBE_FORCE_WAYLAND`	`1`	跳过 `GDK_BACKEND=x11` 强制，用 Wayland 原生
`GDK_BACKEND`	`x11` / `wayland`	直接指定 GTK 后端（一般不需要手动设）
`RUST_BACKTRACE`	`1` / `full`	Rust panic 时打印完整栈
`DISPLAY`	`:0`	X11 显示器（Linux/Unix）

举例：在 Wayland 下测试

EZVIBE_FORCE_WAYLAND=1 npm run tauri:dev

安装包里有什么

以 Linux 的 .deb 为例，安装后：

二进制：/usr/bin/live2d（或类似的）
图标：/usr/share/icons/.../ezviber+.png
Desktop entry：/usr/share/applications/ezviber+.desktop（用于系统应用菜单）
用户配置（运行时生成）：~/.live2D/live2d.conf.json
会话数据（运行时生成）：~/.local/share/com.ezviber.plus/sessions/

卸载

Linux (deb)：sudo apt remove ezviber-plus（用户数据默认保留，需要彻底清掉就再 rm -rf ~/.local/share/com.ezviber.plus/ ~/.live2D/live2d.conf.json）
macOS：把 EzVibeR+.app 拖到废纸篓
Windows：控制面板 → 程序和功能 → EzVibeR+ → 卸载

排错速查

现象	可能原因	解决
`npm install` 失败	Node 版本太低	升到 18+
`cargo build` 报 `webkit2gtk-4.1` 找不到	没装对应系统包	回到 01-系统要求与依赖.md
Linux 启动后桌宠不显示	模型目录为空 + 没看到 `main` 窗口	看托盘 → "显示桌宠"；或检查 `~/.live2D/live2d.conf.json` 的 `model_dir`
Linux 启动后看不到托盘图标	缺 `libappindicator`	装上
macOS 启动后立即退出	Gatekeeper 拦截	系统设置 → 隐私与安全性 → 仍要打开
截图失败 "无可用截图方式"	没装 ImageMagick 且 Portal 不可用	`sudo apt install imagemagick`（Linux）；macOS/Windows 重启应用并授予权限

下一步：03-首次启动配置.md — 装完先配模型目录和 LLM。

4.7 KiB Raw Permalink Blame History Unescape Escape