Claude Code + Tauri v2 桌面应用开发：从零到交付全实战

# macOS
xcode-select --install
brew install rustup
rustup-init

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Windows
# 安装 Visual Studio Build Tools + WebView2
# https://visualstudio.microsoft.com/visual-cpp-build-tools/
winget install Microsoft.WebView2Runtime

# Rust 工具链（Tauri 要求 1.77.2+）
rustup default stable
rustc --version  # 确认 >= 1.77.2

# Node.js（前端构建）
node --version   # 建议 >= 20.x

# Claude Code
npm install -g @anthropic-ai/claude-code
claude --version

# Tauri CLI
cargo install tauri-cli

# 创建一个最小化测试项目
cargo tauri init --template vanilla
cargo tauri dev
# 应弹出空白桌面窗口，环境OK

# Project: Clipboard Manager Desktop App

## Tech Stack
- Tauri v2 (Rust backend)
- Svelte 5 + SvelteKit (frontend)
- Tailwind CSS 4 (styling)
- SQLite via rusqlite (local storage)

## Project Structure
- `src/` - SvelteKit frontend code
- `src-tauri/` - Rust backend code
- `src-tauri/src/main.rs` - Rust entry point
- `src-tauri/src/commands/` - Tauri commands (IPC handlers)
- `src-tauri/tauri.conf.json` - Tauri configuration
- `src-tauri/capabilities/` - Security capability files

## Architecture
- Frontend communicates with Rust backend ONLY via Tauri invoke()
- All file system, database, OS operations happen in Rust
- Frontend never directly accesses Node.js APIs or filesystem

## Key Rules
- Rust commands must use #[tauri::command] macro
- All command parameters must implement Serialize + Deserialize
- Use Result<T, String> for error handling in commands
- Frontend calls: import { invoke } from '@tauri-apps/api/core'
- Events use tauri::AppHandle::emit() from Rust, listen() from frontend

## Build & Run
- `cargo tauri dev` - development mode
- `cargo tauri build` - production build
- `npm run dev` - frontend-only dev (no Rust)

mkdir clipboard-manager && cd clipboard-manager
claude

创建一个 Tauri v2 + SvelteKit 项目。
- 使用 npm create tauri-app@latest -- --template sveltekit
- 项目名 clipboard-manager
- 前端用 SvelteKit + Tailwind CSS
- 创建 CLAUDE.md（使用上面准备的内容）
- 创建 src-tauri/src/commands/ 目录

# Step 1: 脚手架
npm create tauri-app@latest -- clipboard-manager --template sveltekit

# Step 2: 安装依赖
cd clipboard-manager
npm install
npm install -D @tailwindcss/vite tailwindcss

# Step 3: 配置 Tailwind
# 在 vite.config.js 添加 Tailwind 插件

# Step 4: Tauri 依赖
cd src-tauri
cargo add serde --features derive
cargo add rusqlite --features bundled

clipboard-manager/
├── CLAUDE.md                    # 项目规则（核心！）
├── package.json
├── src/                         # SvelteKit 前端
│   ├── routes/
│   │   └── +page.svelte        # 主页面
│   ├── lib/
│   │   └── api.ts              # Tauri invoke 封装
│   └── app.html
├── src-tauri/                   # Rust 后端
│   ├── Cargo.toml
│   ├── tauri.conf.json
│   ├── capabilities/
│   │   └── default.json        # 安全能力配置
│   └── src/
│       ├── main.rs              # 入口 + 插件注册
│       ├── lib.rs               # 命令注册
│       └── commands/
│           ├── mod.rs
│           └── clipboard.rs     # 剪贴板操作命令
└── static/

graph LR
    subgraph Frontend["前端 (WebView)"]
        UI["Svelte 组件"]
        API["api.ts 封装层"]
    end

    subgraph IPC["IPC 桥接"]
        Invoke["invoke()"]
        Event["事件系统"]
        Channel["Channel 流"]
    end

    subgraph Backend["Rust 后端"]
        Cmd["#[tauri::command]"]
        State["StateManager"]
        DB["SQLite / 文件系统"]
    end

    UI --> API --> Invoke --> Cmd
    Cmd --> State --> DB
    DB --> State --> Event --> UI

use serde::{Deserialize, Serialize};
use tauri::State;
use std::sync::Mutex;

#[derive(Serialize, Deserialize, Clone)]
pub struct ClipItem {
    pub id: i64,
    pub content: String,
    pub content_type: String,  // "text" | "image" | "file"
    pub created_at: String,
    pub pinned: bool,
}

pub struct AppState {
    pub db: Mutex<rusqlite::Connection>,
}

#[tauri::command]
pub fn get_clips(
    state: State<'_, AppState>,
    limit: Option<u32>,
) -> Result<Vec<ClipItem>, String> {
    let limit = limit.unwrap_or(50);
    let conn = state.db.lock().map_err(|e| e.to_string())?;

    let mut stmt = conn
        .prepare("SELECT id, content, content_type, created_at, pinned FROM clips ORDER BY created_at DESC LIMIT ?1")
        .map_err(|e| e.to_string())?;

    let items = stmt
        .query_map([limit], |row| {
            Ok(ClipItem {
                id: row.get(0)?,
                content: row.get(1)?,
                content_type: row.get(2)?,
                created_at: row.get(3)?,
                pinned: row.get(4)?,
            })
        })
        .map_err(|e| e.to_string())?
        .collect::<Result<Vec<_>, _>>()
        .map_err(|e| e.to_string())?;

    Ok(items)
}

#[tauri::command]
pub fn save_clip(
    state: State<'_, AppState>,
    content: String,
    content_type: String,
) -> Result<ClipItem, String> {
    let conn = state.db.lock().map_err(|e| e.to_string())?;

    conn.execute(
        "INSERT INTO clips (content, content_type) VALUES (?1, ?2)",
        [&content, &content_type],
    ).map_err(|e| e.to_string())?;

    let id = conn.last_insert_rowid();

    Ok(ClipItem {
        id,
        content,
        content_type,
        created_at: chrono::Utc::now().to_rfc3339(),
        pinned: false,
    })
}

#[tauri::command]
pub fn delete_clip(state: State<'_, AppState>, id: i64) -> Result<(), String> {
    let conn = state.db.lock().map_err(|e| e.to_string())?;
    conn.execute("DELETE FROM clips WHERE id = ?1", [id])
        .map_err(|e| e.to_string())?;
    Ok(())
}

#[tauri::command]
pub fn toggle_pin(state: State<'_, AppState>, id: i64) -> Result<bool, String> {
    let conn = state.db.lock().map_err(|e| e.to_string())?;
    conn.execute(
        "UPDATE clips SET pinned = NOT pinned WHERE id = ?1",
        [id],
    ).map_err(|e| e.to_string())?;

    let pinned: bool = conn
        .query_row("SELECT pinned FROM clips WHERE id = ?1", [id], |row| row.get(0))
        .map_err(|e| e.to_string())?;

    Ok(pinned)
}

mod commands;
use commands::clipboard::{AppState, get_clips, save_clip, delete_clip, toggle_pin};

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    let db = rusqlite::Connection::open_in_memory()
        .expect("failed to open database");

    db.execute_batch(
        "CREATE TABLE IF NOT EXISTS clips (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            content TEXT NOT NULL,
            content_type TEXT NOT NULL DEFAULT 'text',
            created_at TEXT DEFAULT (datetime('now')),
            pinned INTEGER DEFAULT 0
        )"
    ).expect("failed to create table");

    tauri::Builder::default()
        .plugin(tauri_plugin_opener::init())
        .manage(AppState {
            db: std::sync::Mutex::new(db),
        })
        .invoke_handler(tauri::generate_handler![
            get_clips,
            save_clip,
            delete_clip,
            toggle_pin,
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

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

export interface ClipItem {
  id: number;
  content: string;
  content_type: string;
  created_at: string;
  pinned: boolean;
}

export async function getClips(limit?: number): Promise<ClipItem[]> {
  return invoke<ClipItem[]>('get_clips', { limit });
}

export async function saveClip(content: string, contentType: string): Promise<ClipItem> {
  return invoke<ClipItem>('save_clip', { content, contentType });
}

export async function deleteClip(id: number): Promise<void> {
  return invoke('delete_clip', { id });
}

export async function togglePin(id: number): Promise<boolean> {
  return invoke<boolean>('toggle_pin', { id });
}

<script lang="ts">
  import { onMount } from 'svelte';
  import { getClips, saveClip, deleteClip, togglePin, type ClipItem } from '$lib/api';

  let clips: ClipItem[] = $state([]);
  let inputText: string = $state('');
  let loading: boolean = $state(false);

  onMount(async () => {
    await refreshClips();
  });

  async function refreshClips() {
    loading = true;
    try {
      clips = await getClips(100);
    } catch (e) {
      console.error('Failed to load clips:', e);
    } finally {
      loading = false;
    }
  }

  async function handleSave() {
    if (!inputText.trim()) return;
    await saveClip(inputText, 'text');
    inputText = '';
    await refreshClips();
  }

  async function handleDelete(id: number) {
    await deleteClip(id);
    await refreshClips();
  }

  async function handlePin(id: number) {
    await togglePin(id);
    await refreshClips();
  }
</script>

<main class="min-h-screen bg-gray-900 text-white p-6">
  <h1 class="text-2xl font-bold mb-6">📋 Clipboard Manager</h1>

  <div class="flex gap-2 mb-6">
    <input
      bind:value={inputText}
      onkeydown={(e) => e.key === 'Enter' && handleSave()}
      placeholder="粘贴或输入内容..."
      class="flex-1 px-4 py-2 rounded bg-gray-800 border border-gray-700"
    />
    <button onclick={handleSave} class="px-6 py-2 bg-blue-600 rounded hover:bg-blue-500">
      保存
    </button>
  </div>

  {#if loading}
    <p class="text-gray-400">加载中...</p>
  {:else if clips.length === 0}
    <p class="text-gray-400">暂无剪贴板记录</p>
  {:else}
    <div class="space-y-2">
      {#each clips as clip (clip.id)}
        <div class="flex items-center gap-3 p-3 rounded bg-gray-800">
          <span class="flex-1 text-sm truncate">{clip.content}</span>
          <span class="text-xs text-gray-500">{clip.created_at}</span>
          <button
            onclick={() => handlePin(clip.id)}
            class="px-2 py-1 text-xs rounded {clip.pinned ? 'bg-yellow-600' : 'bg-gray-700'}"
          >
            {clip.pinned ? '📌 已置顶' : '置顶'}
          </button>
          <button
            onclick={() => handleDelete(clip.id)}
            class="px-2 py-1 text-xs bg-red-700 rounded hover:bg-red-600"
          >
            删除
          </button>
        </div>
      {/each}
    </div>
  {/if}
</main>

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Default permissions for the app",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "core:window:default",
    "core:window:allow-close",
    "core:window:allow-set-title",
    "opener:default",
    {
      "identifier": "fs:default",
      "allow": [
        { "path": "$APPDATA/**" }
      ]
    }
  ]
}

graph TD
    A["用户操作"] --> B{"需要 OS 权限？"}
    B -->|"否"| C["前端直接处理"]
    B -->|"是"| D["通过 invoke 调用 Rust"]
    D --> E{"能力配置允许？"}
    E -->|"否"| F["❌ 拒绝，返回权限错误"]
    E -->|"是"| G["✅ 执行 Rust 命令"]
    G --> H["返回结果到前端"]

    style F fill:#ef4444
    style G fill:#22c55e

在 src-tauri/src/commands/clipboard.rs 中定义以下命令：
- get_clips(limit: Option<u32>) -> Vec<ClipItem>
- save_clip(content: String, content_type: String) -> ClipItem
- delete_clip(id: i64) -> ()
- search_clips(query: String) -> Vec<ClipItem>

ClipItem 结构体包含：id, content, content_type, created_at, pinned
使用 rusqlite，数据库路径用 tauri::api::path::app_data_dir

根据 src-tauri/src/commands/clipboard.rs 中的 Rust 命令，
生成对应的 TypeScript 封装到 src/lib/api.ts。
使用 invoke() 调用，导出类型安全的函数。

基于 src/lib/api.ts 中的函数，
创建 src/routes/+page.svelte：
- 顶部输入框 + 保存按钮
- 剪贴板列表，每项有：内容预览、时间、置顶按钮、删除按钮
- 置顶项排在最前
- 使用 Tailwind CSS，深色主题

## Tauri Command Rules
- 命令文件统一放在 src-tauri/src/commands/ 目录
- 每个领域一个文件：clipboard.rs, settings.rs, export.rs
- 错误处理统一用 Result<T, String>
- 数据库操作使用 State<AppState> 注入
- 不在 main.rs 中写业务逻辑

## Frontend Rules
- 所有 Tauri 调用封装在 src/lib/api.ts
- UI 组件不直接 import invoke
- 使用 TypeScript 类型对应 Rust 结构体
- CSS 只用 Tailwind 工具类

调试以下 Tauri IPC 调用错误：
- 前端调用：invoke('get_clips', { limit: 50 })
- 错误信息：[粘贴完整错误]
- Rust 命令签名：[粘贴函数签名]
- 检查：参数名是否匹配 snake_case/camelCase 转换规则

use tauri::{AppHandle, Emitter};

#[tauri::command]
pub fn watch_clipboard(app: AppHandle) -> Result<(), String> {
    let handle = app.clone();
    std::thread::spawn(move || {
        // 模拟剪贴板监听
        loop {
            let content = read_clipboard_content();
            if let Some(text) = content {
                let _ = handle.emit("clipboard-changed", text);
            }
            std::thread::sleep(std::time::Duration::from_secs(1));
        }
    });
    Ok(())
}

import { listen } from '@tauri-apps/api/event';

onMount(async () => {
  const unlisten = await listen<string>('clipboard-changed', (event) => {
    console.log('新剪贴板内容:', event.payload);
    refreshClips(); // 自动刷新列表
  });

  return () => unlisten();
});

sequenceDiagram
    participant F as 前端 (Svelte)
    participant T as Tauri Core
    participant R as Rust 后端

    F->>T: invoke("watch_clipboard")
    T->>R: 路由到 watch_clipboard 命令
    R->>R: 启动后台线程监听剪贴板

    loop 每秒检测
        R->>T: emit("clipboard-changed", payload)
        T->>F: 事件回调触发
        F->>T: invoke("get_clips")
        T->>R: 查询数据库
        R-->>F: 返回最新列表
    end

# 构建所有平台的安装包
cargo tauri build

# 输出位置
# macOS: src-tauri/target/release/bundle/dmg/
# Windows: src-tauri/target/release/bundle/msi/
# Linux: src-tauri/target/release/bundle/deb/ 或 appimage/

{
  "productName": "Clipboard Manager",
  "version": "1.0.0",
  "identifier": "com.example.clipboard-manager",
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devUrl": "http://localhost:5173",
    "frontendDist": "../build"
  },
  "app": {
    "windows": [
      {
        "title": "Clipboard Manager",
        "width": 800,
        "height": 600,
        "resizable": true,
        "fullscreen": false
      }
    ],
    "security": {
      "csp": "default-src 'self'; style-src 'unsafe-inline'"
    }
  },
  "bundle": {
    "active": true,
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ],
    "category": "Utility"
  }
}

# macOS
export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"
cargo tauri build --target universal-apple-darwin

# Windows
# 需要购买代码签名证书
cargo tauri build

markdown-notes/
├── CLAUDE.md
├── src/
│   ├── routes/
│   │   ├── +page.svelte          # 笔记列表
│   │   └── edit/[id]/+page.svelte # 编辑页面
│   └── lib/
│       ├── api.ts                # IPC 封装
│       └── markdown.ts           # Markdown 解析
├── src-tauri/
│   └── src/commands/
│       ├── mod.rs
│       ├── notes.rs              # 笔记 CRUD
│       └── export.rs             # 导出 PDF/HTML

创建一个 Tauri v2 + SvelteKit 的 Markdown 笔记应用。

要求：
1. Rust 后端使用 SQLite 存储，包含 notes 表（id, title, content, created_at, updated_at, tags）
2. 实现命令：list_notes, get_note, create_note, update_note, delete_note, search_notes, export_html
3. 前端：
   - 左侧笔记列表（支持搜索、标签过滤）
   - 右侧 Markdown 编辑器（实时预览）
   - 顶部工具栏（新建、删除、导出）
4. 使用 marked.js 解析 Markdown
5. 深色主题，响应式布局
6. 所有文件操作通过 Rust 后端

请按照 CLAUDE.md 中的架构规则，分层实现：
先 Rust 命令，再 API 封装，最后 UI 组件。

# 添加移动端目标
cargo tauri android init
cargo tauri ios init

# 运行 Android
cargo tauri android dev

# 运行 iOS
cargo tauri ios dev

sudo apt install libwebkit2gtk-4.1-dev

# Cargo.toml - 开发时使用优化
[profile.dev]
opt-level = 1

[profile.dev.package."*"]
opt-level = 3

let db_path = app.path().app_data_dir()?.join("data.db");
let db = rusqlite::Connection::open(&db_path)?;

graph TD
    A["1. 项目初始化<br/>cargo tauri init --template sveltekit"] --> B["2. 编写 CLAUDE.md<br/>定义架构规则"]
    B --> C["3. Claude Code 分层驱动<br/>Rust命令 → API层 → UI"]
    C --> D["4. cargo tauri dev<br/>实时联调"]
    D --> E{"功能完整？"}
    E -->|"否"| C
    E -->|"是"| F["5. cargo tauri build<br/>打包安装包"]
    F --> G["6. 代码签名 + 分发"]

    style A fill:#3b82f6,color:#fff
    style B fill:#8b5cf6,color:#fff
    style C fill:#f59e0b,color:#fff
    style D fill:#22c55e,color:#fff
    style F fill:#ef4444,color:#fff
    style G fill:#ec4899,color:#fff