197 lines
4.8 KiB
Markdown
197 lines
4.8 KiB
Markdown
# Tauri Shell
|
||
|
||
一个基于 Tauri v2 的轻量级桌面应用壳子，使用 Sidecar 模式承载主要业务逻辑。
|
||
|
||
## 项目特点
|
||
|
||
- **架构**: Sidecar 模式 - Tauri 仅提供原生桌面能力，Web 逻辑全部由 Sidecar Server 处理
|
||
- **后端**: Rust (Edition 2021)
|
||
- **异步运行时**: Tokio
|
||
- **设计理念**: 分离关注点 - Tauri 负责原生功能（文件对话框、系统通知等），Sidecar 负责业务逻辑
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Rust 1.92.0+
|
||
- Tauri CLI v2
|
||
- Node.js (用于前端构建，如果有的话)
|
||
|
||
推荐使用 [mise](https://mise.jdx.dev/) 管理工具版本（见 `mise.toml`）。
|
||
|
||
### 开发运行
|
||
|
||
```bash
|
||
# 开发模式（带 hot-reload）
|
||
tauri dev
|
||
|
||
# 仅运行 Rust 二进制
|
||
cargo run
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
# 开发构建
|
||
cargo build
|
||
|
||
# 生产构建
|
||
cargo build --release
|
||
|
||
# 打包应用（生成安装程序）
|
||
tauri build
|
||
```
|
||
|
||
## Sidecar 配置
|
||
|
||
### Sidecar 命名规则
|
||
|
||
Tauri 使用平台特定的命名约定来识别 Sidecar 二进制文件。在 `tauri.conf.json` 中配置基础名称，Tauri 会自动根据目标平台添加后缀。
|
||
|
||
#### 配置示例
|
||
|
||
```json
|
||
{
|
||
"bundle": {
|
||
"externalBin": [
|
||
"binaries/server"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 平台命名规则
|
||
|
||
Tauri 会根据以下规则查找对应平台的二进制文件：
|
||
|
||
| 平台 | 架构 | 文件名格式 | 示例 |
|
||
|------|------|-----------|------|
|
||
| **Windows** | x64 | `{name}-x86_64-pc-windows-msvc.exe` | `server-x86_64-pc-windows-msvc.exe` |
|
||
| **Windows** | ARM64 | `{name}-aarch64-pc-windows-msvc.exe` | `server-aarch64-pc-windows-msvc.exe` |
|
||
| **macOS** | Intel (x64) | `{name}-x86_64-apple-darwin` | `server-x86_64-apple-darwin` |
|
||
| **macOS** | Apple Silicon | `{name}-aarch64-apple-darwin` | `server-aarch64-apple-darwin` |
|
||
| **Linux** | x64 | `{name}-x86_64-unknown-linux-gnu` | `server-x86_64-unknown-linux-gnu` |
|
||
| **Linux** | ARM64 | `{name}-aarch64-unknown-linux-gnu` | `server-aarch64-unknown-linux-gnu` |
|
||
|
||
**重要提示**：
|
||
- `{name}` 是 `externalBin` 中配置的基础名称（不含路径）
|
||
- Windows 平台的可执行文件必须包含 `.exe` 扩展名
|
||
- macOS 和 Linux 平台的二进制文件无扩展名
|
||
- 文件必须放在 `binaries/` 目录中
|
||
|
||
#### 目录结构示例
|
||
|
||
```
|
||
tauri-shell/
|
||
├── binaries/
|
||
│ ├── .gitignore
|
||
│ ├── server-x86_64-pc-windows-msvc.exe # Windows x64
|
||
│ ├── server-aarch64-pc-windows-msvc.exe # Windows ARM64
|
||
│ ├── server-x86_64-apple-darwin # macOS Intel
|
||
│ ├── server-aarch64-apple-darwin # macOS Apple Silicon
|
||
│ ├── server-x86_64-unknown-linux-gnu # Linux x64
|
||
│ └── server-aarch64-unknown-linux-gnu # Linux ARM64
|
||
└── tauri.conf.json
|
||
```
|
||
|
||
### Sidecar 进程管理
|
||
|
||
本项目在 `src/sidecar.rs` 中实现了以下功能：
|
||
|
||
1. **自动端口扫描**: 从端口 3000 开始查找可用端口
|
||
2. **环境变量注入**: 通过 `NITRO_PORT` 等变量配置 Sidecar
|
||
3. **进程生命周期管理**: 应用退出时自动清理子进程
|
||
4. **超时处理**: 启动超时设置为 5 秒
|
||
|
||
#### 使用示例
|
||
|
||
```rust
|
||
use tauri::Manager;
|
||
|
||
// 在 lib.rs 中启动 sidecar
|
||
tauri::async_runtime::spawn(async move {
|
||
sidecar::spawn_sidecar(app_handle.clone()).await;
|
||
});
|
||
|
||
// 在应用退出时清理
|
||
app.run(move |app_handle, event| {
|
||
sidecar::cleanup_sidecar_process(app_handle, &event);
|
||
});
|
||
```
|
||
|
||
## 开发指南
|
||
|
||
### 代码检查
|
||
|
||
```bash
|
||
# 编译检查
|
||
cargo check
|
||
|
||
# 代码质量检查
|
||
cargo clippy
|
||
|
||
# 格式化检查
|
||
cargo fmt -- --check
|
||
|
||
# 自动格式化
|
||
cargo fmt
|
||
```
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
cargo test
|
||
|
||
# 显示测试输出
|
||
cargo test -- --nocapture
|
||
```
|
||
|
||
### 提交前检查
|
||
|
||
- [ ] `cargo fmt` 格式化通过
|
||
- [ ] `cargo clippy` 无警告
|
||
- [ ] `cargo check` 编译通过
|
||
- [ ] `cargo test` 测试通过
|
||
- [ ] 验证 Tauri 应用正常启动和退出
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
tauri-shell/
|
||
├── src/
|
||
│ ├── main.rs # 入口文件
|
||
│ ├── lib.rs # 核心应用逻辑
|
||
│ ├── commands/
|
||
│ │ └── mod.rs # Tauri 命令定义
|
||
│ └── sidecar.rs # Sidecar 进程管理
|
||
├── binaries/ # Sidecar 二进制文件
|
||
├── capabilities/ # Tauri v2 权限配置
|
||
├── icons/ # 应用图标资源
|
||
├── Cargo.toml # Rust 项目配置
|
||
├── tauri.conf.json # Tauri 应用配置
|
||
└── mise.toml # 开发工具版本管理
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- **Tauri**: v2 (桌面应用框架)
|
||
- **Rust**: Edition 2021
|
||
- **Tokio**: 异步运行时
|
||
- **Serde**: 序列化/反序列化
|
||
- **Tauri Plugins**:
|
||
- `tauri-plugin-shell`: Shell 和 Sidecar 支持
|
||
- `tauri-plugin-opener`: 文件/URL 打开支持
|
||
|
||
## 详细文档
|
||
|
||
- [AGENTS.md](./AGENTS.md) - AI 编程助手和开发者指南，包含详细的代码风格规范
|
||
|
||
## License
|
||
|
||
MIT
|
||
|
||
## 作者
|
||
|
||
imbytecat
|