114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
# 02 · 安装与运行
|
||
|
||
## 最快跑起来（开发模式）
|
||
|
||
> 适合：第一次跑通、边改边看效果、调 UI。
|
||
|
||
```bash
|
||
# 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](03-首次启动配置.md) 设置模型目录。
|
||
|
||
## 三平台的生产构建
|
||
|
||
### 一条命令搞定当前平台
|
||
|
||
```bash
|
||
# 完整打包（前端类型检查 + 前端 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。
|
||
|
||
### 各平台分步构建（可选）
|
||
|
||
```bash
|
||
# 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 下测试
|
||
```bash
|
||
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](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](03-首次启动配置.md) — 装完先配模型目录和 LLM。
|