安装
安装依赖并在开发环境运行桌面应用。
本页从全新 clone 开始，带你打开 Electron 开发窗口。开发命令会以 watch 模式运行 electron-vite，并同时启动 main、preload 与 renderer 三个 bundle。
前置要求
| 工具 | 版本 | 说明 |
|---|---|---|
| Node.js | `^20.19.0 | |
| pnpm | 11.1.3 | package.json 的 packageManager 已固定该版本，建议用 Corepack。 |
普通开发不需要平台 SDK。签名、公证与各目标安装包验证会在 Packaging 页面处理。
安装并运行
clone 模板并进入项目目录。
git clone <your-repo-url> my-desktop-app
cd my-desktop-app安装依赖。
pnpm installpostinstall 会运行 electron-builder install-app-deps，为当前平台重建
Electron 原生依赖。
创建本地环境配置。
cp .env.example .env当前 renderer 在挂载前会校验 VITE_SUPABASE_URL 与
VITE_SUPABASE_PUBLISHABLE_KEY。只看外壳时可以暂留示例值；测试认证、
profile、avatar、todos 或计费前，请替换为真实 Supabase 项目。
启动 Electron 开发应用。
pnpm devscripts/dev.mjs 包装了 electron-vite dev -w。在 Linux 上，它会为缺少
Electron SUID sandbox helper 的开发机设置 ELECTRON_DISABLE_SANDBOX=1。
默认 feature flags 下，认证和自动更新界面开启，计费关闭，Showcase 演示开启。
计费在 VITE_BILLING_ENABLED=true 前保持隐藏；Supabase 认证/数据示例需要真实
Supabase 值才有意义。
验证安装
pnpm dev 启动后，检查这些界面：
- 桌面窗口打开，并显示自定义标题栏与侧边栏外壳。
- Home 渲染；showcase flags 开启时，Showcase 与 Components 入口可见。
Cmd/Ctrl+K能打开命令面板。- Settings 中修改主题或语言后，重启仍然保留。
- 首次运行 onboarding 会出现，完成后不再出现。
- Logs 和 About 能显示诊断信息且不会暴露 secret。
脚本
| 命令 | 用途 |
|---|---|
pnpm dev | 以 watch 模式启动 Electron 与 Vite。 |
pnpm start | 用 electron-vite preview 预览已构建应用。 |
pnpm lint | 运行 ESLint 并自动修复。 |
pnpm lint:check | 使用 --max-warnings=0 运行 ESLint。 |
pnpm typecheck | 对 node 与 web 配置运行 tsc -b --noEmit。 |
pnpm test | 运行核心 Vitest 套件。 |
pnpm test:all | 运行所有 Vitest 配置。 |
pnpm test:smoke | 构建应用，并用 VITE_E2E_BYPASS_AUTH=true 运行 Playwright 冒烟测试。 |
pnpm build:mac | 用 electron-builder 构建 macOS 分发包。 |
pnpm build:win | 构建 Windows NSIS 安装包。 |
pnpm build:linux | 构建 Linux AppImage、Snap 与 Deb。 |
pnpm build:unpack | 构建未打包应用目录，不生成安装器。 |
pnpm supabase:deploy | 部署 supabase/functions 中的 Supabase Edge Functions。 |
pnpm analyze:bundle | 分析 Electron/Vite bundle 输出。 |
pnpm rebrand | 重写产品名、slug、app id、scheme 与相关资源。 |
修改模板前的最低验证：
pnpm lint:check
pnpm typecheck
pnpm test改动路由、外壳、认证 gate 或桌面 IPC 时，再运行 pnpm test:smoke。
首次运行故障
| 现象 | 可能原因 | 处理 |
|---|---|---|
| Vite 或 electron-vite 拒绝启动 | Node 低于支持范围 | 安装 Node ^20.19.0 或 >=22.12.0。 |
| pnpm 提示包管理器版本 | 本地 pnpm 不匹配 pnpm@11.1.3 | 启用 Corepack，并运行 corepack prepare pnpm@11.1.3 --activate。 |
| 原生模块 rebuild 报错 | postinstall 未完成 | 重新运行 pnpm install；必要时删除 node_modules 后用支持的 Node 版本重装。 |
| 出现 Supabase 配置错误屏 | 缺少或无效的 VITE_SUPABASE_URL / VITE_SUPABASE_PUBLISHABLE_KEY | 复制 .env.example 为 .env，设置两项后重启 pnpm dev。 |
| Linux 窗口打开前失败 | 本地 sandbox helper 不可用 | 使用 pnpm dev；包装脚本只会在 Linux 开发环境设置 ELECTRON_DISABLE_SANDBOX=1。 |
| 开发端口被占用 | 另一个 Vite/Electron 会话仍在运行 | 停止旧会话，或结束占用端口的进程。 |