# 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。