3.2 脚手架实操：创建并跑通第一个项目

环境就绪，本节把全册示例"随身笔记"工程真正立起来：走完脚手架的每一步问答，逐目录看清工程结构，跑通 dev 热更新与首次构建。本节结束时的工程是此后所有章节的操作基座——建议跟着做，别只读。

创建：一次交互问答

npm create tauri-app@latest
​

问答逐项过（括号内是本册的选择与理由）：

• Project name：travel-notes（全册示例名，起名用小写加连字符，省去后续标识符转义）；
• Identifier：com.example.travel-notes（反向域名格式，全球唯一即可；注意不要以 .app 结尾——macOS 打包时会与应用包目录名冲突）；
• Frontend language：TypeScript（类型在跨语言项目里是保险绳，5.1 节会展开）；
• Package name / UI template：Vanilla（本节用零依赖的最小模板讲清结构；第 4 章再接入 Vue 对比）；
• UI flavor：TypeScript。

创建完成后按提示安装依赖并启动：

cd travel-notes
npm install
npm run tauri dev
​

第一次 tauri dev 会先起前端 dev 服务，再编译整个 Rust 依赖树——几分钟的等待属于正常首次成本，之后增量编译以秒计。编译完成，桌面弹出窗口，hello world 到手。

拆开看：目录即架构

把工程树与第 2 章的三层装配图对齐着看：

travel-notes/
├── index.html            # 前端入口：壳加载的第一个页面
├── src/                  # 前端源码
│   ├── main.ts           # 前端逻辑：按钮事件、invoke 调用
│   └── assets/           # 静态样式与图
├── package.json          # 前端工程清单；scripts 里的 tauri 命令是两端总开关
└── src-tauri/            # 芯工程，独立完整的 Rust 项目
    ├── Cargo.toml        # Rust 依赖：tauri、插件、业务库都登记在此
    ├── build.rs
    ├── tauri.conf.json   # 装配说明书（3.3 节逐段精读）
    ├── capabilities/     # 权限清单：default.json 声明窗口可用能力
    ├── icons/            # 图标全家桶：由 icon 命令生成
    └── src/
        ├── main.rs       # 薄入口，三行，调 lib 的 run
        └── lib.rs        # 命令、初始化、Builder 装配
​

两个结构性事实需要点透。其一，这是双工程结构：前端工程与 Rust 工程各自有独立的依赖清单与构建体系，tauri-cli 负责把两者的构建串成流水线（8.1 节展开）。其二，main.rs 是薄壳：真正的装配逻辑在 lib.rs 的 run 函数里——这个安排是为移动端预留的（移动入口以库形式链接），桌面项目也应保持这个习惯，别把逻辑塞回 main.rs。

图 3-2：工程目录标注图

跑通两条流水线

dev 模式（日常开发）：npm run tauri dev。它做三件事——起前端 dev 服务、增量编译 Rust、把 WebView 指向 dev 服务。改前端代码热更新立现；改 Rust 代码自动重编译并重启窗口。开发期的窗口加载的是本地服务地址而非最终资源，这一点在 3.3 的 build 段会对应上。

首次构建（交付预演）：npm run tauri build。前端先按生产模式打包，Rust 再按 release 配置编译，最后走打包器产出安装包。首次 release 编译比 dev 更久（开了优化），产出的安装包在输出目录里。本节只验证"能出包"，包的类型与瘦身在第 8 章专门讲。

首跑排错：三个常见症状

脚手架理论上一次跑通，实际总有环境意外。症状一：dev 启动后窗口白屏。 多是前端 dev 服务没起来或端口对不上——看终端里前端服务的启动日志，确认实际端口与配置 devUrl 一致（3.3 节详述）；也可能是浏览器安全软件拦了本地服务，白名单放行即可。症状二：Rust 编译中途报错。 第一行报错通常点名缺什么：Windows 缺链接组件、Linux 缺 WebKitGTK、依赖版本冲突——按 3.1 的备料清单核对，或按报错提示补装。症状三：改了 Rust 代码窗口没重启。 保存的文件确实在 src-tauri 里吗？有些编辑器默认保存到临时区；另外 Builder 配置若写了条件编译分支，确认改动的代码在被编译的分支里。三个症状的共同排查起点都是看终端输出——dev 模式的全部日志都在那里，先读后猜。

还有一条团队协作的提醒：src-tauri 目录里的 target 文件夹是编译产物，体积大且与机器相关，务必让版本控制忽略它；同样被忽略的还有前端构建产物目录。脚手架生成的忽略规则已涵盖，自己迁移存量工程时记得补齐，否则第一次提交仓库就会塞进上千个文件。

工程立起来后：先做三件定制

模板只是毛坯，动手改三处，工程才有"这是我的项目"的实感，也顺带把"改哪层"的手感建立起来。**第一件，改名字与窗口。**窗口标题在配置的 app.windows 段（3.3 精读），改完保存——Rust 配置改动会触发重编译重启，正好感受一次自动重启链路。**第二件，认领芯侧的第一行代码。**模板在 lib.rs 里自带一条 greet 命令，把它的返回串改成中文并带上参数值，保存后点击页面按钮，窗口里立刻显示新文案——这一来一回就是 2.2 那条传送带的实体：前端 invoke、桥上路由、芯里执行、结果序列化回来。

// src-tauri/src/lib.rs —— 模板自带的示例命令，改出你的第一行芯代码
#[tauri::command]
fn greet(name: &str) -> String {
    format!("你好，{name}！欢迎登上随身笔记。")
}
​

**第三件，验证热更新边界。**故意在前端代码里写出一个类型错误，观察 dev 服务的报错浮层；再故意在命令函数里写一个编译错误，观察终端里的 cargo 报错与窗口的重启行为。五分钟的故意破坏，换来的是对"哪端错误在哪端报"的直观认识——前端错误不上终端、Rust 错误不进页面浮层，这个界限感在后面所有章节的排错里都会用到。

三件定制做完，提交一版到版本控制，打上"工程基座"标签。此后每章的改动都在这个基座上增量进行，出了问题随时能回到已知良好状态——这是跟着做与本册示例保持同步的锚点。

本节要点回顾

• 问答四要害：项目名小写、Identifier 反向域名且不以 .app 结尾、前端语言选 TS、模板可从 Vanilla 起步；
• 双工程结构：前端与 src-tauri 各自独立，只在构建流水线与 IPC 上交界；
• main.rs 保持薄：装配逻辑住 lib.rs，为移动端预留也为了整洁；
• dev 三件事：起前端服务、增量编译、窗口指向 dev 服务；Rust 改动自动重启；
• build 首次较慢：release 优化所致，产物是安装包，细节留给第 8 章。

工程能跑了，下一节精读装配说明书 tauri.conf.json——把第 2 章图纸上的每个零件对上配置文件里的具体条目。