创建第一个应用并跑通

环境就绪后，本篇带你看一个完整的 Tauri 项目长什么样：目录结构、配置文件、开发命令与调试技巧。读完后你应当能独立创建项目、修改界面、写一个自己的 Rust 命令并在开发模式下看到效果。

一、用脚手架创建项目

仍然使用官方脚手架，一行命令完成骨架：

npm create tauri-app@latest my-app

脚手架会问你几个问题：包管理器（npm、pnpm、yarn）、前端语言（JavaScript、TypeScript）以及框架（Vue、React、Svelte、Vanilla）。以 Vue 加 TypeScript 为例，生成的目录结构大致如下：

可以看到 Tauri 项目只是把一个标准前端项目套上一层 Rust 壳。前端的构建工具、路由、状态管理都不用换，已有的前端知识完全可以迁移过来，这也是它上手快的原因之一。

二、开发命令与热重载

日常开发只记两条命令：

npm run tauri dev   # 开发模式，前端热更新加 Rust 重编译
npm run tauri build # 构建安装包

开发模式下前端走 Vite 的 HMR，改界面秒级生效；修改 Rust 代码则会触发重新编译并重启应用。首次 Rust 全量编译较慢，后续增量编译会快不少，这点需要心理准备。

Rust 端入口在 src-tauri/src/main.rs，最小形态如下：

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|_app| {
            println!("应用启动完成");
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

generate_context! 宏会在编译期读取 tauri.conf.json 与图标资源，把配置固化进二进制，运行时不再依赖外部配置文件，API 形态以官方文档为准。

三、写第一个命令并调用

光有道具有意思的部分来了：加一个加法命令。在 main.rs 中：

#[tauri::command]
fn add(a: i32, b: i32) -> i32 {
    a + b
}

pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![add])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

前端调用：

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

const sum = await invoke('add', { a: 1, b: 2 })
console.log(sum) // 3

注意命令必须注册到 generate_handler! 里，否则前端调用会报 「command not found」 之类的错误。参数名采用 camelCase 与 Rust 端 snake_case 对应，例如 Rust 的 file_name 前端传 fileName，具体规则以官方文档为准。更完整的命令系统（返回值序列化、错误抛出、自定义类型）见「前端调用 Rust：invoke 与命令系统」。

四、调试技巧

调试分两层。前端调试照常：开发模式下应用窗口里右键即可打开开发者工具，或者用 F12 快捷键，断点、网络面板都可用。

Rust 端调试推荐用 VS Code 的 rust-analyzer 加 CodeLLDB，配置好 launch 后可以断点进 Rust 代码。快速排错时，println! 配合终端输出也完全够用，tauri dev 运行时 Rust 进程的日志会打印在终端里。

五、项目跑通后的下一步

能够创建项目、写命令、调试之后，建议先补齐两块：一是 Rust 入门 的语法基础，让命令写得更顺手；二是运行原理，理解 IPC 在背后怎么传递数据，后续遇到奇怪问题才好定位，详见「运行原理：WebView、IPC 与进程模型」。如果你习惯用 AI 辅助写样板代码，Claude Code 指南 里有不少可复用的经验。

六、给新手的项目检查清单

第一次跑通项目后，拿这张清单逐项确认，能避免后面大量返工：

其中 git 忽略是细节但很重要：src-tauri/target 编译产物体积大，误提交会让仓库迅速膨胀。Tauri 脚手架会生成合适的 .gitignore，自己接管项目时要确认两端的忽略文件都配好。

跑通只是起点。接下来真正决定应用质量的是通信、状态与错误处理三块，对应本书的三个重点章节：命令系统、事件系统与全局状态。有了骨架之后补齐这三块，应用才算立住。

走到这里，你对 Tauri 项目的全貌已经有了手感：脚手架建骨架，Vite 管前端，Rust 管能力，配置文件管形态。接下来正式进入通信机制的学习。顺序建议是先读命令系统把单向请求跑顺，再读事件系统掌握双向通知，最后用全局状态把数据流串起来。三块学完，你就能独立完成绝大多数功能需求，剩下的只是熟练度问题。

第一次构建编译时间长的另一个原因值得分开说：Rust 的增量编译依赖 target 目录缓存，而杀毒软件有时会扫描并锁定 target 里的文件，导致编译莫名失败或变慢。遇到「昨天还能编译今天突然不行」的情况，先把项目目录加进杀毒白名单试试。这个经验在 Windows 上尤其有效，是社区里反复被验证过的解决方案之一，属于环境排错清单里的常规项。

第一次跑通项目的成就感值得珍惜，但也要克制立刻堆功能的冲动。先花一小时把项目结构理顺：前端按页面分目录、Rust 按功能分模块、命令集中注册。这个阶段建立的结构纪律，会在功能膨胀到二十个命令时救你一命。目录组织没有金标准，团队顺手、新人易懂就是好结构，随应用长大再迭代。下一章进入运行原理，把开发中每个「为什么」补齐。

多叮嘱一句开发节奏：不要在最初的项目里追求高级特性。先把同步命令写熟，再碰事件系统，最后才考虑异步与自定义插件，每一步都让应用真正跑起来再往前走。Tauri 的学习曲线集中在 Rust 与权限两块，把这两块的耐心留足，后面的路一马平川。下一章运行原理会把现在「能跑但是不知道为什么」的部分逐层讲清，理解了原理，调试与排错才真正有方向，而不是全靠搜索引擎。

当你的第一个应用窗口弹出来的那一刻，最难的一关已经过了——从「想」到「做到」的距离，往往就在这第一次跑通里。继续保持这份手感，本书会把它变成真正的产品能力。

延伸阅读

• Rust 入门：让 Rust 命令写得更顺手
• 运行原理：WebView、IPC 与进程模型——理解两层通信的下一站
• tauri.conf.json 核心配置速查——项目跑通后必然要改的配置