integrating-tauri-js-frontends

用途

该技能面向使用 Tauri v2 开发桌面应用的场景，帮助 Claude 为 JavaScript 前端框架完成与 Tauri 的集成配置。Tauri 本身作为静态 Web 宿主运行，通过原生 WebView 提供 HTML、CSS、JavaScript 和 WASM 文件，因此前端框架需要针对静态输出进行适配。

主要能力

技能覆盖以下框架的集成配置：

Vite（React、Vue、Svelte、Solid）：推荐用于 SPA 框架，开发体验快、配置简单。
Next.js：需使用静态导出模式。
Nuxt：需以 SSG 模式运行并设置 ssr: false。
SvelteKit：需使用静态适配器并禁用 SSR。
Qwik：需使用静态适配器。

支持的应用类型包括静态站点生成（SSG）、单页应用（SPA）和多页应用（MPA）。不支持原生形式的服务端渲染（SSR），所有框架都必须配置为静态输出。

使用方式

核心原则：

静态输出必需：Tauri 无法运行 Node.js 服务器，所有内容必须预构建为静态文件。
客户端-服务器架构：在应用与 API 之间实现正确的客户端-服务器关系，不使用混合 SSR 方案。
移动开发：需要开发服务器在内部 IP 上托管前端。

通用 tauri.conf.json 结构：

{
  "build": {
    "beforeDevCommand": "<package-manager> dev",
    "beforeBuildCommand": "<package-manager> build",
    "devUrl": "http://localhost:<port>",
    "frontendDist": "../<output-dir>"
  }
}

其中 <package-manager> 可替换为 npm run、yarn、pnpm 或 deno task。

各框架关键配置要点：

Vite：在 vite.config.ts 中设置 clearScreen: false、server.port、strictPort、host、watch.ignored 包含 **/src-tauri/**，envPrefix 为 ['VITE_', 'TAURI_ENV_*']，并根据 TAURI_ENV_PLATFORM 设置 build.target（windows 用 chrome105，其他用 safari13）。
Next.js：next.config 中必须设置 output: 'export'，images.unoptimized: true，开发时配置 assetPrefix 指向开发服务器。输出目录为 out。动态路由需 generateStaticParams()，不支持 API 路由，应改用 Tauri 命令。
Nuxt：nuxt.config.ts 中设置 ssr: false、telemetry: false、devServer.host 为 '0.0.0.0'（iOS 设备兼容需要），vite 配置类似 Vite。生产构建使用 nuxt generate。不支持 server routes（/server/api），应改用 Tauri 命令。
SvelteKit：安装 @sveltejs/adapter-static，svelte.config.js 中配置 adapter 并设置 fallback: 'index.html'，在 src/routes/+layout.ts 中导出 ssr = false 和 prerender = true。输出目录默认为 build/。推荐使用 SPA 模式（不预渲染）以便在 load 函数中访问完整 Tauri API。
Qwik：创建项目后运行 npm run qwik add static 添加静态适配器，安装 @tauri-apps/cli，运行 npm run tauri init 初始化。Qwik City 服务器函数不可用，应改用 Tauri 命令。

快速参考表：

框架	输出目录	开发端口	构建命令	关键配置
Vite	dist	5173	vite build	标准 Vite 配置
Next.js	out	3000	next build	output: 'export'
Nuxt	dist	3000	nuxt generate	ssr: false
SvelteKit	build	5173	vite build	adapter-static
Qwik	dist	5173	qwik build	静态适配器

环境变量：

TAURI_DEV_HOST：移动开发的主机 IP。
TAURI_ENV_PLATFORM：目标平台（windows、macos、linux、ios、android）。
TAURI_ENV_DEBUG：调试构建时设置。
推荐 envPrefix：['VITE_', 'TAURI_ENV_*']。

移动开发：iOS 和 Android 开发时，开发服务器必须可在网络上访问，设置 server.host 为 process.env.TAURI_DEV_HOST || '0.0.0.0'，并使用 npm run tauri ios dev 或 npm run tauri android dev 运行。

适用场景

适用于需要将现代 JavaScript 前端框架与 Tauri v2 桌面应用集成的开发工作，包括桌面端 SPA、SSG 应用以及面向 iOS/Android 的移动开发。

限制

不支持原生服务端渲染（SSR），所有框架必须配置为静态输出。
无法运行 Node.js 服务器。
Next.js 不支持 API 路由，Nuxt 不支持 server routes，Qwik 不支持 Qwik City 服务器函数，这些后端功能应改用 Tauri 命令实现。
使用预渲染时，load 函数在构建时执行，无法访问 Tauri API。

常见问题与解决方案

开发时资源不加载：未为开发服务器配置 asset prefix，需配置 asset prefix 指向开发服务器。
Tauri API 不可用：代码在 SSG 构建时而非运行时执行，需对使用 Tauri API 的页面禁用预渲染，使用 ssr: false 的动态导入，或在调用 API 前检查 window.TAURI。
热重载不工作：文件监视器包含了 src-tauri 目录，需在 Vite 配置的 watch ignore 列表中添加 **/src-tauri/**。
移动开发失败：开发服务器无法在网络上访问，需将 host 设为 0.0.0.0 或使用 TAURI_DEV_HOST 环境变量。
构建因 SSR 错误失败：框架尝试服务端渲染，需确保禁用 SSR（Next.js 用 output: 'export'，Nuxt 用 ssr: false，SvelteKit 在 layout 中导出 ssr = false，Qwik 使用静态适配器）。

技能介绍

用途

主要能力

使用方式

适用场景

限制

常见问题与解决方案