Qwik + Tauri 实战指南用静态导出把 Qwik 应用装进桌面应用里

1. 接入原则 Checklist（为什么必须这么做）

使用 SSG：Tauri 不支持依赖服务端渲染（SSR）的运行模式，你不能指望在 Tauri 里跑一个 Node 服务器给页面提供 SSR
将 dist/ 作为 frontendDist：Tauri 打包时需要一个静态目录，把它嵌进应用里或作为资源加载入口

2. 从零创建 Qwik 项目

bash 复制代码

npm create qwik@latest
cd <PROJECT>

建议创建时就选一个偏 SPA/SSG 的模板，减少后续改造成本。

3. 安装 Static Adapter（把 Qwik 变成"可静态部署"）

这一步是整合成功的核心：让 Qwik 构建产物落到 dist/ 并且可纯静态运行。

bash 复制代码

npm run qwik add static

完成后，你的 npm run build 才会更像"生成静态站点"，这正是 Tauri 需要的形态。

4. 安装 Tauri CLI（Node 方式）

你可以用 Cargo 安装 tauri-cli，也可以按 Qwik 这条路线直接用 npm 装 CLI。这里按你给的流程：

bash 复制代码

npm install -D @tauri-apps/cli@latest

这会让你可以用 npm run tauri ... 的方式调用 CLI。

5. 初始化 Tauri 项目（生成 src-tauri 与配置）

bash 复制代码

npm run tauri init

执行后会生成 src-tauri/ 目录，以及 src-tauri/tauri.conf.json 等文件。后续桌面窗口、权限、打包等都在这里配置。

6. 配置 tauri.conf.json：告诉 Tauri 怎么跑前端、产物在哪

把（或合并）下面的 build 配置写到 src-tauri/tauri.conf.json 里。注意：你贴的示例里 devUrl 后少了逗号，我这里修正成合法 JSON。

json 复制代码

{
  "build": {
    "devUrl": "http://localhost:5173",
    "frontendDist": "../dist",
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build"
  }
}

字段含义很直观：

beforeDevCommand：你跑 tauri dev 前，先启动 Qwik 的 dev server
devUrl：Tauri 开发模式下 WebView 加载的地址（通常是 Vite 5173）
beforeBuildCommand：你跑 tauri build 前，先构建前端静态资源
frontendDist：构建产物目录（相对 src-tauri/，所以是 ../dist）

7. 启动 Tauri 开发模式：一条命令看到桌面窗口

bash 复制代码

npm run tauri dev

它会做两件事：

启动 npm run dev（Qwik dev server）
编译并启动 Tauri，打开桌面窗口加载 http://localhost:5173

看到窗口打开并加载页面，就说明"前端 + Tauri"链路打通了。

8. 常见问题与排查思路

8.1 打包后白屏

优先检查这三项：

npm run build 后是否真的生成了 dist/
frontendDist 是否指向正确（尤其是 monorepo 时目录层级容易错）
前端是否仍依赖 SSR/服务端能力（例如某些路由/数据加载必须服务端执行）

8.2 devUrl 访问正常但 Tauri 窗口加载失败

确认端口固定（不要被 dev server 自动换端口）
确认 devUrl 和实际 dev server 地址一致

8.3 未来要做移动端真机调试

移动端一般要求 dev server 能被手机访问（绑定内网 IP），你需要让 dev server 监听到可被设备发现的地址，并让 Tauri 使用正确的 host。等你要上移动端时，我可以按你的网络环境给你一份"Qwik dev server 绑定 + HMR 配置"的最稳模板。

9. 最小可用工作流总结

创建：npm create qwik@latest
静态化：npm run qwik add static
初始化 Tauri：npm install -D @tauri-apps/cli@latest + npm run tauri init
开发：npm run tauri dev
构建发布：npm run tauri build（同理，前端先 build，再由 Tauri 打包）