# Tauri 桌面端开发笔记

> 记录 ZCLAW Desktop Tauri 开发过程中的经验和注意事项。

---

## 1. 项目结构

```
desktop/
├── src/                    # React 前端
│   ├── components/         # UI 组件
│   ├── store/              # Zustand 状态管理
│   ├── lib/                # 工具库
│   └── App.tsx             # 入口组件
├── src-tauri/              # Tauri Rust 后端
│   ├── src/
│   │   ├── lib.rs          # 主入口
│   │   └── main.rs         # 主函数
│   ├── Cargo.toml          # Rust 依赖
│   ├── tauri.conf.json     # Tauri 配置
│   └── build.rs            # 构建脚本
├── package.json
└── vite.config.ts
```

---

## 2. 开发命令

### 2.1 常用命令

```bash
# 启动开发服务器 (Vite + Tauri)
pnpm tauri dev

# 仅启动前端 (Vite)
pnpm dev

# 构建生产版本
pnpm tauri build

# 类型检查
pnpm tsc --noEmit
```

### 2.2 命令说明

| 命令 | 说明 | 端口 |
|------|------|------|
| `pnpm dev` | 仅 Vite 开发服务器 | 1420 |
| `pnpm tauri dev` | Tauri + Vite | 1420 (Vite) + Native Window |
| `pnpm tauri build` | 生产构建 | - |

---

## 3. 配置文件

### 3.1 tauri.conf.json 关键配置

```json
{
  "build": {
    "beforeDevCommand": "pnpm dev",
    "beforeBuildCommand": "pnpm build",
    "devPath": "http://localhost:1420",
    "distDir": "../dist"
  },
  "tauri": {
    "windows": [
      {
        "title": "ZCLAW",
        "width": 1200,
        "height": 800,
        "resizable": true,
        "fullscreen": false
      }
    ],
    "security": {
      "csp": "default-src 'self'; connect-src 'self' ws://localhost:* ws://127.0.0.1:*"
    }
  }
}
```

### 3.2 Vite 配置

```typescript
// vite.config.ts
export default defineConfig({
  plugins: [react()],
  server: {
    port: 1420,
    strictPort: true,
    proxy: {
      '/api': {
        target: 'http://127.0.0.1:50051',
        changeOrigin: true,
        secure: false,
        ws: true,  // WebSocket 支持
      },
    },
  },
});
```

---

## 4. 常见问题

### 4.1 端口占用

**症状**: `Port 1420 is already in use`

**解决方案**:

```powershell
# 查找占用进程
netstat -ano | findstr "1420"

# 终止进程
Stop-Process -Id <PID> -Force
```

### 4.2 Tauri 编译失败

**常见原因**:

1. **Rust 版本过低**
   ```bash
   rustup update
   ```

2. **依赖缺失**
   ```bash
   # Windows 需要 Visual Studio Build Tools
   # 安装: https://visualstudio.microsoft.com/visual-cpp-build-tools/

   # 确保 C++ 工作负载已安装
   ```

3. **Cargo 缓存问题**
   ```bash
   cd desktop/src-tauri
   cargo clean
   cargo build
   ```

### 4.3 窗口白屏

**排查步骤**:

1. 检查 Vite 开发服务器是否运行
2. 打开 DevTools (F12) 查看控制台错误
3. 检查 `tauri.conf.json` 中的 `devPath`

**解决方案**:

```typescript
// 确保在 tauri.conf.json 中启用 devtools
{
  "tauri": {
    "windows": [{
      "devtools": true  // 开发模式下启用
    }]
  }
}
```

### 4.4 热重载不工作

**检查**:

1. `beforeDevCommand` 是否正确配置
2. 文件监听限制 (Linux)
   ```bash
   echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
   sudo sysctl -p
   ```

---

## 5. IPC 通信

### 5.1 Rust 端暴露命令

```rust
// src-tauri/src/lib.rs
#[tauri::command]
fn get_app_version() -> String {
    env!("CARGO_PKG_VERSION").to_string()
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![
            get_app_version,
            // 其他命令
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

### 5.2 前端调用

```typescript
import { invoke } from '@tauri-apps/api/core';

const version = await invoke<string>('get_app_version');
```

### 5.3 常用 Tauri API

| API | 用途 |
|-----|------|
| `@tauri-apps/api/core` | invoke, convertFileSrc |
| `@tauri-apps/api/window` | 窗口管理 |
| `@tauri-apps/api/shell` | 执行 shell 命令 |
| `@tauri-apps/api/fs` | 文件系统 |
| `@tauri-apps/api/path` | 路径 API |

---

## 6. 安全配置

### 6.1 CSP 配置

```json
{
  "tauri": {
    "security": {
      "csp": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; connect-src 'self' ws://localhost:* ws://127.0.0.1:* http://127.0.0.1:*; font-src 'self' https://fonts.gstatic.com"
    }
  }
}
```

### 6.2 允许的协议

确保 CSP 允许：
- `ws://localhost:*` - 本地 WebSocket
- `ws://127.0.0.1:*` - ZCLAW WebSocket
- `http://127.0.0.1:*` - ZCLAW REST API

---

## 7. 本地 Gateway 集成

### 7.1 Bundled Runtime

ZCLAW Desktop 可以捆绑 ZCLAW Runtime：

```
desktop/src-tauri/resources/
└── zclaw-runtime/
    ├── zclaw.exe
    ├── config/
    └── ...
```

### 7.2 启动本地 Gateway

```rust
#[tauri::command]
async fn start_local_gateway(app: AppHandle) -> Result<(), String> {
    let resource_path = app.path_resolver()
        .resource_dir()
        .ok_or("Failed to get resource dir")?;

    let zclaw_path = resource_path.join("zclaw-runtime/zclaw.exe");

    // 启动进程
    Command::new(zclaw_path)
        .args(["start"])
        .spawn()
        .map_err(|e| e.to_string())?;

    Ok(())
}
```

### 7.3 检测 Gateway 状态

```typescript
// 前端检测
async function checkGatewayStatus(): Promise<'running' | 'stopped'> {
  try {
    const response = await fetch('http://127.0.0.1:50051/api/health');
    if (response.ok) {
      return 'running';
    }
  } catch {
    // Gateway 未运行
  }
  return 'stopped';
}
```

---

## 8. 构建发布

### 8.1 构建命令

```bash
pnpm tauri build
```

输出位置：
```
desktop/src-tauri/target/release/
├── desktop.exe          # 可执行文件
└── bundle/
    ├── msi/             # Windows 安装包
    └── nsis/            # NSIS 安装包
```

### 8.2 构建配置

```json
{
  "tauri": {
    "bundle": {
      "identifier": "com.zclaw.desktop",
      "icon": ["icons/32x32.png", "icons/128x128.png", "icons/icon.ico"],
      "targets": ["msi", "nsis"],
      "windows": {
        "certificateThumbprint": null,
        "digestAlgorithm": "sha256",
        "timestampUrl": ""
      }
    }
  }
}
```

### 8.3 减小体积

```toml
# Cargo.toml
[profile.release]
lto = true
codegen-units = 1
panic = "abort"
strip = true
```

---

## 9. 调试技巧

### 9.1 启用 DevTools

开发模式下自动启用，生产模式需要在配置中启用：

```json
{
  "tauri": {
    "windows": [{
      "devtools": true
    }]
  }
}
```

### 9.2 日志记录

```rust
use log::{info, error};

#[tauri::command]
fn some_command() -> Result<String, String> {
    info!("Command called");
    // ...
    Ok("result".to_string())
}
```

### 9.3 前端调试

```typescript
// 开发模式下启用详细日志
if (import.meta.env.DEV) {
  console.log('[Debug]', ...args);
}
```

---

## 10. 性能优化

### 10.1 延迟加载

```typescript
// 延迟加载非关键组件
const Settings = lazy(() => import('./components/Settings'));
const HandsPanel = lazy(() => import('./components/HandsPanel'));
```

### 10.2 状态优化

```typescript
// 使用 selector 避免不必要渲染
const messages = useChatStore((state) => state.messages);
// 而不是
const store = useChatStore();
const messages = store.messages; // 会导致所有状态变化都重渲染
```

---

## 更新历史

| 日期 | 变更 |
|------|------|
| 2026-03-14 | 初始版本 |