Next.js + Tauri 2 用 Static Export 把 React 元框架装进桌面/移动端

1. 适配清单 Checklist

• 开启静态导出：output: 'export'（Tauri 不支持 SSR 那种"必须有服务端"的方案）。 (Tauri)
• tauri.conf.json 里把 frontendDist 指到 ../out（Next 静态导出目录）。 (Tauri)
• 如果你用了 next/image，必须处理图片优化：静态导出下默认的图片优化 API 不可用，最简单就是 images.unoptimized = true。 (Tauri)
• 开发态资源路径要能解析：按官方建议加 assetPrefix，让 dev server 正确解析静态资源（尤其在非 localhost/移动端调试时）。 (Tauri)

2. Tauri 配置：src-tauri/tauri.conf.json

这段的意义是：tauri dev 先跑 Next dev server，再让 WebView 加载 devUrl；tauri build 先跑 Next build（生成 out），再把 out 打包进应用。Tauri CLI 正是按这些字段工作的。 (Tauri)

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

(Tauri)

提示：frontendDist 是相对 src-tauri/ 的路径，所以 Next 项目在根目录时通常就是 ../out。

3. Next.js 配置：next.config.mjs

这份配置解决三件大事：

1. 强制静态导出 output: 'export'
2. next/image 走静态导出时禁用默认优化（否则直接报错）
3. 开发态设置 assetPrefix，避免资源解析错误（文档建议）

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;

(Tauri)

补充理解一下 images.unoptimized：

静态导出下，Next 默认的 Image Optimization API（按需优化）不可用，所以必须禁用或换方案。官方错误说明写得很明确。 (nextjs.org)

4. package.json scripts：确保 Tauri 能"按脚本驱动"前端

你给的 scripts 很标准，Tauri CLI 会调用你在 beforeDevCommand/beforeBuildCommand 里写的命令，所以这里保证能跑就行：

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

(Tauri)

5. 运行与打包：你只需要记住两条命令

• 开发：

  • cargo tauri dev（会先执行 npm run dev，再加载 http://localhost:3000） (Tauri)

• 构建：

  • cargo tauri build（会先执行 npm run build，把静态导出生成到 out/，再打包） (Tauri)

Next 的静态导出产物就是 out/，构建后你会看到 out/index.html、out/404.html 等文件结构。 (nextjs.org)

6. 你需要接受的"静态导出"边界

把 Next 变成静态站点后，这些能力要重新规划（否则你会在 build 时报错或运行时缺功能）：

• 不依赖服务端运行时：SSR、需要 Node 运行时的 API Routes、中间件等都要迁移到独立后端服务（保持"客户端 ↔ API"的标准模式）。 (nextjs.org)
• 动态路由要可静态化：要么在构建期生成，要么改成纯客户端拉取数据再渲染（这和 Tauri 的模型更贴）。 (nextjs.org)

7. 常见坑与排查（很实用）

7.1 打包后白屏

优先按顺序查这三项：

• out/ 是否真的生成（执行 npm run build 后是否有 out/index.html）。 (nextjs.org)
• tauri.conf.json 的 frontendDist 是否正确指向 ../out。 (Tauri)
• 资源路径是否被你自定义了 basePath/assetPrefix 导致找不到 JS/CSS（打开 DevTools 看 Network 404）。

7.2 next/image 报错：Image Optimization 不兼容导出

这是经典报错场景，直接按文档处理：images.unoptimized: true 或换图片策略。 (nextjs.org)

7.3 开发态热更新不工作，和 assetPrefix 相关

社区里确实有人反馈：某些组合下 assetPrefix 会影响 hot reload 表现。你如果遇到"编译提示更新但页面不刷新"，可以把它当作已知问题来对待：

• 先尝试升级到更新版本的 Tauri/Next
• 或临时注释 assetPrefix 验证是否是它引起
• 若必须保留资源解析能力，考虑把 dev server host 配置到可直连的内网地址并调整 devUrl（移动端场景更常见） (GitHub)