integrating-tauri-js-frontends

Tauri v2 JavaScript 前端集成

本技能介绍如何将 JavaScript 前端框架与 Tauri v2 集成，用于桌面应用开发。

核心架构

Tauri 充当静态 Web 主机，通过原生 WebView 提供 HTML、CSS、JavaScript 和 WASM 文件。该框架不依赖特定前端框架，但需要进行特定配置以实现最佳集成效果。

支持的应用类型

• 静态站点生成（SSG）
• 单页应用（SPA）
• 多页应用（MPA）

不支持

不支持原生形式的服务端渲染（SSR）。所有框架都必须配置为输出静态文件。

一般要求

核心原则

1. 必须输出静态文件：Tauri 无法运行 Node.js 服务端，所有内容都必须预先构建为静态文件
2. 客户端-服务端架构：在应用和 API 之间建立合适的客户端-服务端关系（不使用混合 SSR 方案）
3. 移动端开发：需要使用开发服务端，通过你的内部 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（React、Vue、Svelte、Solid）

对于 SPA 框架，推荐使用 Vite，因为它开发体验快捷，且配置简单。

package.json

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "tauri": "tauri"
  }
}

vite.config.ts

import { defineConfig } from 'vite';

export default defineConfig({
  clearScreen: false,
  server: {
    port: 5173,
    strictPort: true,
    host: process.env.TAURI_DEV_HOST || 'localhost',
    watch: {
      ignored: ['**/src-tauri/**'],
    },
  },
  envPrefix: ['VITE_', 'TAURI_ENV_*'],
  build: {
    target: process.env.TAURI_ENV_PLATFORM === 'windows' ? 'chrome105' : 'safari13',
    minify: process.env.TAURI_ENV_DEBUG ? false : 'esbuild',
    sourcemap: !!process.env.TAURI_ENV_DEBUG,
  },
});

tauri.conf.json

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

---

Next.js

由于 Tauri 无法运行 Node.js 服务端，Next.js 必须使用静态导出模式。

重要要求

• 必须在 next.config 中使用 output: 'export'
• 静态导出时必须禁用图片优化
• 开发服务端需要设置资源前缀

next.config.mjs

const isProd = process.env.NODE_ENV === 'production';
const internalHost = process.env.TAURI_DEV_HOST || 'localhost';

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  assetPrefix: isProd ? undefined : `http://${internalHost}:3000`,
};

export default nextConfig;

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "tauri": "tauri"
  }
}

tauri.conf.json

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

Next.js 的 SSG 注意事项

• out 目录包含静态导出内容
• 动态路由需要使用 generateStaticParams()
• 不支持 API 路由，请改用 Tauri 命令
• next/image 优化已禁用；请使用标准 <img>，或配置为不进行优化

---

Nuxt

Nuxt 必须以 SSG 模式运行，并设置 ssr: false，才能兼容 Tauri。

nuxt.config.ts

export default defineNuxtConfig({
  ssr: false,
  telemetry: false,
  devServer: {
    host: '0.0.0.0', // Required for iOS device compatibility
  },
  vite: {
    clearScreen: false,
    envPrefix: ['VITE_', 'TAURI_'],
    server: {
      strictPort: true,
      watch: {
        ignored: ['**/src-tauri/**'],
      },
    },
  },
});

package.json

{
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "generate": "nuxt generate",
    "tauri": "tauri"
  }
}

tauri.conf.json

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

Nuxt 的 SSG 注意事项

• 使用 nuxt generate 构建生产版本（生成静态文件）
• 无法使用服务端路由（/server/api），请改用 Tauri 命令
• SSG 模式下会禁用 Nitro 服务端功能

---

SvelteKit

SvelteKit 必须使用静态适配器，并禁用 SSR。

安装

npm install --save-dev @sveltejs/adapter-static

svelte.config.js

import adapter from '@sveltejs/adapter-static';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter({
      fallback: 'index.html',
    }),
  },
};

export default config;

src/routes/+layout.ts

export const ssr = false;
export const prerender = true;

vite.config.ts

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [sveltekit()],
  clearScreen: false,
  server: {
    port: 5173,
    strictPort: true,
    host: process.env.TAURI_DEV_HOST || 'localhost',
    watch: {
      ignored: ['**/src-tauri/**'],
    },
  },
  envPrefix: ['VITE_', 'TAURI_ENV_*'],
});

tauri.conf.json

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

SvelteKit 的 SSG 注意事项

• 推荐使用 SPA 模式（不进行预渲染），以便在 load 函数中完整访问 Tauri API
• 使用预渲染时，load 函数会在构建时执行，无法访问 Tauri API
• fallback: 'index.html' 可启用 SPA 路由
• 默认输出目录为 build/

---

Qwik

Qwik 必须使用静态适配器，才能兼容 Tauri。

设置

# Create project
npm create qwik@latest
cd <project>

# Add static adapter
npm run qwik add static

# Add Tauri CLI
npm install -D @tauri-apps/cli@latest

# Initialize Tauri
npm run tauri init

package.json

{
  "scripts": {
    "dev": "vite",
    "build": "qwik build",
    "tauri": "tauri"
  }
}

tauri.conf.json

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

Qwik 的 SSG 注意事项

• 必须使用静态适配器
• 无法使用 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	静态适配器

---

常见问题与解决方案

问题：开发环境中无法加载资源

原因：未为开发服务器配置资源前缀。

解决方案：将资源前缀配置为指向开发服务器（参见 Next.js 配置示例）。

问题：Tauri API 不可用

原因：代码在 SSG 构建时执行，而不是在运行时执行。

解决方案：

• 禁用使用 Tauri API 的页面的预渲染
• 使用带有 ssr: false 的动态导入
• 在调用 API 前检查 window.__TAURI__

问题：热重载无法正常工作

原因：文件监视器包含 src-tauri 目录。

解决方案：在 Vite 配置中的监视忽略列表里添加 **/src-tauri/**。

问题：移动端开发失败

原因：开发服务器无法通过网络访问。

解决方案：将主机设置为 0.0.0.0，或使用 TAURI_DEV_HOST 环境变量。

问题：构建因 SSR 错误而失败

原因：框架尝试进行服务器端渲染。

解决方案：确保已禁用 SSR：

• Next.js：output: 'export'
• Nuxt：ssr: false
• SvelteKit：在布局中设置 export const ssr = false
• Qwik：使用静态适配器

---

环境变量

Tauri 提供的变量

变量	描述
TAURI_DEV_HOST	移动端开发的主机 IP
TAURI_ENV_PLATFORM	目标平台（windows、macos、linux、ios、android）
TAURI_ENV_DEBUG	在调试构建期间设置

推荐的 envPrefix

envPrefix: ['VITE_', 'TAURI_ENV_*']

---

构建目标

根据平台 WebView 的功能配置构建目标：

build: {
  target: process.env.TAURI_ENV_PLATFORM === 'windows'
    ? 'chrome105'  // WebView2 on Windows
    : 'safari13',  // WebKit on macOS/Linux
}

---

移动端开发

对于 iOS 和 Android 开发，开发服务器必须能够通过网络访问：

server: {
  host: process.env.TAURI_DEV_HOST || '0.0.0.0',
  strictPort: true,
}

使用相应的移动端命令运行：

npm run tauri ios dev
npm run tauri android dev