在 Next.js + Tauri 桌面应用中，app/not-found.tsx 在开发时正常，但 tauri build 后 404 路由失效——本质是 next export 生成纯静态文件，丢失服务端路由匹配能力，需通过客户端路由劫持+HTML fallback 机制手动补全。
在 next.js + tauri 桌面应用中，`app/not-found.tsx` 在开发时正常，但 `tauri build` 后 404 路由失效——本质是 `next export` 生成纯静态文件，丢失服务端路由匹配能力，需通过客户端路由劫持+html fallback 机制手动补全。
当使用 next export（即 output: "export"）构建 Next.js 应用并集成 Tauri 时，整个应用被编译为静态 HTML/JS/CSS 文件，不再存在 Node.js 服务端运行时。这意味着：
- ✅
app/not-found.tsx在开发模式（next dev）下由 Next.js 服务端自动拦截未匹配路由并渲染，因此cargo tauri dev能正常工作； - ❌
cargo tauri build后，Tauri 加载的是out/目录下的静态资源，所有路由均由前端浏览器 History API 或文件系统路径直接解析，Next.js 的路由匹配与错误边界（如not-found.js、error.js）完全失效； - ? 浏览器访问
/non-existent-path时，Tauri 默认回退到index.html（即根页面），因此你看到的是/app/page.tsx渲染的内容，而 URL 仍保持/non-existent-path—— 这正是典型的「客户端单页应用（SPA）404 失效」现象。
✅ 正确解决方案：客户端路由兜底 + 静态 fallback
由于没有服务端参与，我们必须在浏览器端主动识别无效路径并渲染 404 UI。推荐两种互补策略：
1. 利用 next export 的 404.html 静态兜底（最简可靠）
Next.js export 模式原生支持生成 404.html（注意：仅对 Pages Router 有效，但 App Router 可兼容适配）：
✅ 操作步骤：
- 在项目根目录创建
public/404.html（注意不是app/下）：<meta charset="UTF-8"><title>Not Found - Scribble</title><style> body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100vh; background: #f9fafb; text-align: center; } h1 { font-size: 3rem; color: #1f2937; margin-bottom: 1rem; } .emoji { font-size: 2.5rem; line-height: 1.2; } a { display: inline-block; margin-top: 1.5rem; padding: 0.5rem 1.5rem; background: #3b82f6; color: white; text-decoration: none; border-radius: 0.5rem; } </style><h1>Not Found!</h1> <div class="emoji">|、<br>(˚ˎ 。7<br>|、˜〵<br>じしˍ,)ノ</div> <a href="/">Go to home</a> <script> // 关键：强制重写 URL 为 /404，避免历史栈污染 if (window.location.pathname !== '/404') { history.replaceState({}, '', '/404'); } </script>
⚠️ 重要说明：
Comprehensive Three.js 3D graphics reference
下载
详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。
-
public/404.html会被next export自动识别，并在请求任何不存在路径时由 Tauri Webview 直接返回该 HTML（无需 JS 执行）； - 此方案零依赖、100% 静态、SEO 友好，且 HTTP 状态码默认为
404（Tauri 内部处理）； - 不需要修改
app/not-found.tsx，它在export模式下本就不生效。
2. 前端 React 路由增强（可选，用于 SPA 体验优化）
若需保留 React 组件逻辑（如样式复用、按钮交互、动画等），可在 app/layout.tsx 或 _app.tsx（Pages Router）中注入客户端路由检测：
// app/layout.tsx（App Router）
'use client';
import { useEffect } from 'react';
import { usePathname } from 'next/navigation';
export default function RootLayout({
children,
}: { children: React.ReactNode }) {
const pathname = usePathname();
useEffect(() => {
// 检查当前路径是否为已知有效路由（简单白名单，生产环境建议预生成路由清单）
const validRoutes = ['/', '/about', '/settings']; // 替换为你的实际路由
const isNotFound = !validRoutes.some(route =>
pathname === route ||
pathname.startsWith(`${route}/`) // 支持嵌套路由
);
if (isNotFound && typeof window !== 'undefined') {
// 动态加载 404 组件（或跳转）
import('@/app/not-found').then(({ default: NotFound }) => {
// 注入到 DOM（需配合 CSS 隐藏默认内容）
const root = document.getElementById('root');
if (root) {
root.innerHTML = '';
const notFoundEl = document.createElement('div');
notFoundEl.id = 'not-found-root';
document.body.appendChild(notFoundEl);
const rootEl = ReactDOM.createRoot(notFoundEl);
rootEl.render(<notfound></notfound>);
}
});
}
}, [pathname]);
return (
{children}
);
}
? 提示：此方式复杂度高、易出竞态问题，强烈推荐优先使用
public/404.html方案。它更轻量、更稳定、更符合静态部署本质。
? 补充配置检查（关键！）
确保以下配置正确，否则 404.html 不生效：
-
next.config.mjs中output: "export"✅（已满足）； -
tauri.conf.json中build.distDir指向../out，且next export输出目录确实为out/； - 构建前执行
yarn build→ 触发next export→ 生成out/404.html； - 检查
out/404.html是否真实存在（若缺失，说明next export未生成，需排查构建脚本）。
✅ 总结：三步落地
-
删掉对
app/not-found.tsx的依赖——它在export+ Tauri 场景下无意义； -
创建
public/404.html，内容可复用你原有的 JSX 结构（转为 HTML + 内联样式）； -
验证构建产物：运行
yarn build && cargo tauri build，打开out/404.html确认存在，再测试任意非法路径。
至此，你的 Tauri 桌面应用将拥有真正语义化（HTTP 404）、高性能、零 JS 依赖的自定义错误页——既专业，又可靠。
