安装
安装工具链——Node、pnpm、Rust 与各平台 webview 依赖——并在开发模式下运行桌面应用。
本页带你从全新克隆走到一个运行中的桌面窗口。pnpm dev 会运行 tauri dev：
它编译 Rust 外壳，在端口 1420 提供 Vite 前端，然后打开带热重载的应用窗口。
前置条件
与 Web 模板不同，Tauri 会构建原生二进制文件，因此除 Node 之外你还需要 Rust 工具链和平台的 webview 库。
| 工具 | 版本 | 说明 |
|---|---|---|
| Node.js | ^20.19.0 || >=22.12.0 | Vite 工具链要求。 |
| pnpm | 11.1.3 | 由 package.json 的 packageManager 锁定；用 Corepack 保持该版本。 |
| Rust | stable（经 rustup） | 编译 src-tauri crate。 |
| webview 依赖 | 按平台 | 见下方标签与 Tauri 前置条件指南 获取权威包列表。 |
安装 Xcode 命令行工具和 Rust 工具链：
xcode-select --install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh系统自带 WKWebView，无需额外的 webview 运行时。
安装 Microsoft C++ Build Tools（MSVC 工具链）、WebView2 运行时
（Windows 11 预装；安装器也会通过 downloadBootstrapper 获取），以及来自
rustup.rs 的 Rust 工具链。
安装 WebKitGTK 组件与构建基础工具。在 Debian/Ubuntu 上：
sudo apt update
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shlibayatana-appindicator3-dev 支撑系统托盘；请按你的发行版核对包名。
安装并运行
克隆模板并进入项目目录。
git clone <your-repo-url> my-desktop-app
cd my-desktop-app安装依赖。
pnpm install创建本地环境配置。
cp .env.example .env示例值足以启动外壳。当 VITE_AUTH_ENABLED 开启（默认）时，应用会在挂载前
校验 VITE_SUPABASE_URL 与 VITE_SUPABASE_PUBLISHABLE_KEY——.env.example
中的占位值可通过校验，但在测试认证、资料、头像、todos 或计费前，请替换为
真实的 Supabase 项目。
在开发模式下启动桌面应用。
pnpm dev首次 pnpm dev 会编译整个 Rust crate，可能需要数分钟——这是正常现象，
并非卡死。之后的运行是增量的，几秒即可启动。
使用默认开关时，关闭认证后应用可在完全没有后端的情况下启动，或在开启时
连接你的 Supabase 项目。pnpm dev:web 单独运行 Vite 前端以便快速迭代 UI，但它
没有任何原生界面——命令、深链、托盘与钥匙串在其中都不可用。
后端预期
- 默认开关： 认证开、自动更新开、计费关、展示开。
- 还没有 Supabase 项目？ 外壳会用占位 env 运行；登录只是会对不存在的项目失败。
- 计费在
VITE_BILLING_ENABLED=true且设置了 Creem env 之前保持关闭（见 计费）。 - 关闭认证（
VITE_AUTH_ENABLED=false）会移除所有登录界面，应用作为纯本地 桌面工具运行。
验证安装
窗口打开后，检查以下界面：
- 窗口带无边框自定义标题栏（
decorations: false）与侧边栏外壳。 - 首页与展示渲染正常（开关开启时“展示”会出现）。
Cmd/Ctrl+K打开命令面板。- 一次设置修改（主题或语言）在你重启应用后仍保留。
- 首启引导在你完成前会一直出现。
脚本
| 命令 | 用途 |
|---|---|
pnpm dev | 运行 tauri dev：Rust 外壳 + Vite 前端，带热重载。 |
pnpm dev:web | 单独运行 Vite 前端（无原生界面）。 |
pnpm build | 运行 tauri build：完整发布打包（安装包）。 |
pnpm build:web | 仅类型检查并构建前端 bundle。 |
pnpm preview | 用 Vite 预览已构建的前端。 |
pnpm lint / pnpm lint:check | ESLint 自动修复 / 门禁（--max-warnings=0）。 |
pnpm format / pnpm format:check | Prettier 写入 / 检查。 |
pnpm typecheck | 对 node 与 web 配置运行 tsc -b --noEmit。 |
pnpm test | 快速核心 Vitest 套件（test:core）。 |
pnpm test:all | 全部 Vitest 配置。 |
pnpm rebrand | 重写品牌名、slug、app id、协议与静态配置。 |
pnpm supabase:deploy | 部署 Supabase Edge Functions。 |
pnpm tauri icon <src.png> | 重新生成应用 + 托盘图标。 |
这里的 lint 是 Prettier + ESLint，包管理器是 pnpm——不是 Biome。没有
test:smoke 脚本；端到端测试位于独立的 WebdriverIO + tauri-driver 套件
test/e2e/，带自己的 package.json（见 打包）。
完整验证门禁
在完成涉及应用代码、依赖、Tauri 配置、命令/能力、持久化或打包的改动前，运行 README 的质量门禁：
pnpm format:check && pnpm lint:check && pnpm typecheck && pnpm test:unit \
&& cargo fmt --check --manifest-path src-tauri/Cargo.toml \
&& cargo clippy --manifest-path src-tauri/Cargo.toml -- -D warnings \
&& cargo test --manifest-path src-tauri/Cargo.toml三条 cargo 命令覆盖 Rust 部分；cargo test 还会重新生成 src/lib/bindings.ts，
因此绑定漂移会使门禁失败。pnpm tauri build --no-bundle 是一次完整发布编译（数分钟）
——在里程碑而非每一步运行。
首次运行故障
| 现象 | 可能原因 | 处理 |
|---|---|---|
窗口打开前因 webkit2gtk/WebView2/链接错误而构建失败 | 缺少 Rust 或平台 webview 依赖 | 按你的系统安装前置条件（见上方标签）。 |
首次 pnpm dev 数分钟内像是卡住 | 首次 Rust 编译很慢 | 等待——初次 crate 编译属预期，之后是增量。 |
| pnpm 提示包管理器不匹配 | 本地 pnpm ≠ pnpm@11.1.3 | 运行 corepack enable 再 corepack prepare pnpm@11.1.3 --activate。 |
Vite 无法绑定端口 1420 | 另一个开发会话占用该端口 | 停掉另一个会话；端口由 tauri.conf.json 的 devUrl 固定。 |
| Linux：没有托盘图标 | 缺少 AppIndicator 库 | 安装 libayatana-appindicator3-dev 后重启。 |
| macOS：出现钥匙串访问提示 | 未签名的开发构建用登录钥匙串做安全存储 | 属预期——允许即可；签名构建使用应用身份。 |