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 管理工具版本（见 mise.toml）。

开发运行

# 开发模式（带 hot-reload）
tauri dev

# 仅运行 Rust 二进制
cargo run

构建

# 开发构建
cargo build

# 生产构建
cargo build --release

# 打包应用（生成安装程序）
tauri build

Sidecar 配置

Sidecar 命名规则

Tauri 使用平台特定的命名约定来识别 Sidecar 二进制文件。在 tauri.conf.json 中配置基础名称，Tauri 会自动根据目标平台添加后缀。

配置示例

{
  "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 秒

使用示例

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);
});

开发指南

代码检查

# 编译检查
cargo check

# 代码质量检查
cargo clippy

# 格式化检查
cargo fmt -- --check

# 自动格式化
cargo fmt

测试

# 运行所有测试
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 - AI 编程助手和开发者指南，包含详细的代码风格规范

License

MIT

作者

imbytecat