Files

imbytecat 368563c685 docs: 添加项目初始化文档，包含完整使用说明

- 添加项目初始化文档，包含架构说明、快速开始、Sidecar 配置、开发指南及项目结构等完整使用说明。

2026-01-17 15:34:07 +08:00

4.8 KiB

Raw Permalink Blame History

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 中实现了以下功能：

自动端口扫描: 从端口 3000 开始查找可用端口
环境变量注入: 通过 NITRO_PORT 等变量配置 Sidecar
进程生命周期管理: 应用退出时自动清理子进程
超时处理: 启动超时设置为 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

4.8 KiB Raw Permalink Blame History Unescape Escape