故障排查
常见桌面模板问题、原因与修复。
这是简要的 symptom → cause → fix 索引。先查看日志页面和
pnpm dev terminal，通常能找到根本错误。
| 症状 | 可能原因 | 修复 |
|---|
| Rust 或 webview dependency error | 缺少平台 prerequisites | 安装 Rust 以及 macOS CLT、Windows MSVC/WebView2，或 Linux WebKitGTK/AppIndicator packages。参见 Installation。 |
首次 pnpm dev 像卡住一样 | 初始 Rust compilation | 等待首次 crate build；之后会使用 incremental builds。 |
| Port 1420 已被使用 | 另一个 Vite process 正在运行 | 停止该 process，或释放 devUrl 配置的端口。 |
| Blank window | Frontend exception、CSP problem 或 webview 不可用 | 运行 pnpm dev，检查输出与日志，再检查 themed error fallback。 |
| WebView2 missing | Windows runtime 不可用 | 安装 WebView2；bundled installer 使用 download bootstrapper。 |
| 症状 | 可能原因 | 修复 |
|---|
SupabaseConfigErrorScreen | Auth 开启但 Supabase URL/key 缺失或无效 | 设置 VITE_SUPABASE_URL、VITE_SUPABASE_PUBLISHABLE_KEY，或关闭 auth。参见 Authentication。 |
| Auth/Billing 返回后未打开应用 | Scheme 未注册，或 redirect 未配置 | 检查 tauri.conf.json 中 rebrand 后的 scheme 和 Supabase Auth URL Configuration。Windows development 请测试 installed build 或使用文档中的 run-once workaround。参见 Deep Links。 |
| Billing 不见或无法解锁 | Flag、product IDs、webhook 或 entitlement row 缺失 | 开启 VITE_BILLING_ENABLED，设置 product IDs，然后确认 webhook 写入 subscriptions。参见 Creem Setup。 |
| Webhook signature failed | Edge secret 错误 | 使用 supabase secrets set 重设 CREEM_WEBHOOK_SECRET；它不能出现在 app .env。 |
| 症状 | 可能原因 | 修复 |
|---|
Keychain prompt 或 ENCRYPTION_UNAVAILABLE | OS keychain 不可用，或 macOS 请求 unsigned-dev access | 确保 OS keychain 正常；接受预期的 macOS development prompt。参见 Settings Store。 |
| Linux tray 缺失 | 没有 AppIndicator dependencies，或 desktop environment 不支持 tray | 安装 AppIndicator prerequisites，并在支持 tray 的桌面环境中测试。 |
| Bindings-drift CI failure | Rust command types 已改变，但未提交 bindings | 运行 cargo test --manifest-path src-tauri/Cargo.toml，检查 src/lib/bindings.ts 并提交生成的修改。 |
| 显示 raw translation key | Locale key 缺失 | 在 EN 和 ZH locale files 及 namespace registration 中加入该 key。参见 Internationalization。 |
| 症状 | 可能原因 | 修复 |
|---|
| Gatekeeper 报 damaged 或阻止 app | macOS build 未签名或未 notarize | 对 distribution build 签名并 notarize；development build 不能代表 distribution test。参见 Packaging。 |
| SmartScreen warning | Windows installer 没有 reputation 或签名 | 使用 WINDOWS_CERTIFICATE 签名；EV certificate 可立即获得 reputation。 |
| Update signature mismatch | Feed 使用的 private key 与 configured public key 不配对 | 使用匹配 minisign key pair 重新 build/sign，并发布匹配 artifacts。参见 Auto-Update。 |
| Update check 无法访问 feed | Endpoint 错误或 manifest/artifact 缺失 | 检查 runtime/build UPDATE_SERVER_URL、latest.json 和其中所有 URL/signature。 |
| Linux package 不会 self-update | 安装的是 deb 或 rpm | 使用发行版 package manager 或手动下载；只有 AppImage 支持 updater。 |
