TanStack Router 刷新页面出现 404 但应用内导航正常怎么排查【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router在 TanStack Router或基于它的 TanStack Start SPA mode应用中点链接、调用navigate()都能正常跳转但直接刷新页面或在地址栏输入深层 URL 访问时就出现 404。这是docs/router/how-to/deploy-to-production.md中记录的典型问题Routes work when navigating within the app, but refreshing the page shows 404。它的根因是应用内导航由客户端路由处理不经过服务器而刷新时服务器会去查找类似/about/index.html这样的文件单页应用里这些文件并不存在于是服务器返回 404。排查的目标是把 404 的来源定位清楚再补上对应的路由回退配置。整篇按先判断来源、再修服务器回退、最后验证的顺序展开。先判断 404 是服务器返回的还是路由自己渲染的打开浏览器开发者工具的 Network 面板刷新那个出问题的 URL观察主文档请求服务器直接返回 404 状态说明请求根本没有被回退到index.html或 SPA shell属于部署配置问题走下面的补回退配置路径。debug-router-issues.md也建议在网络面板里专门检查 Failed requests — Look for 404s。服务器返回了 200 和应用入口但页面显示的是应用自己的 Not Found 页面说明回退本身没问题问题出在客户端路由匹配走下面的检查路由定义路径。debug-router-issues.md给这类情况的判断依据是症状 Route exists but shows 404 or Not Found并提示控制台会出现路由匹配失败的日志。路径 B服务器回退正常但路由匹配失败对照docs/router/how-to/debug-router-issues.md的 Route Not Found (404) 一节逐项检查检查路由 path 定义。文档指出的常见错误是顶层路由漏掉前导斜杠// ❌ Common mistake - missing leading slash const route createRoute({ path: about, // Should be /about }) // ✅ Correct const route createRoute({ path: /about, })核对路由树结构。在控制台打印路由树确认目标路由确实注册进去了console.log(Route tree:, router.routeTree) console.log(All routes:, router.routesById)检查父路由配置。子路由的getParentRoute必须返回正确的父路由const childRoute createRoute({ getParentRoute: () parentRoute, // Must return correct parent path: /child, })文档的 Common Error Messages → Route not found 小节给出同样的三项检查检查路由路径的拼写和大小写、确认路由已加入 route tree、确认父路由配置正确。如果方便还可以按文档建议安装tanstack/router-devtools它的 Route Matching 面板可以直接显示当前 URL 匹配了哪条路由。注意一个边界如果应用内导航本来就能正常到达该页面路由是匹配成功的那么这种情况基本可以排除重点放在路径 A。路径 A服务器缺少客户端路由回退这是文档记录的主因。解决办法是按托管平台配置所有未命中静态文件的请求都回退到应用入口。deploy-to-production.md的原则是Configure your hosting platform to serveindex.htmlfor all routes, allowing TanStack Router to handle navigation。Nginx自托管最常用在 server block 中加入try_files回退location / { try_files $uri $uri/ /index.html; }Netlify在public/下创建_redirects文件/* /index.html 200或者用根目录的netlify.toml[[redirects]] from /* to /index.html status 200 [build] publish dist command npm run buildVercel根目录创建vercel.json{ rewrites: [ { source: /(.*), destination: /index.html } ] }GitHub Pages它不支持 catch-all 回退文档要求的做法是让构建产出的404.html复制自index.html# After building cp dist/index.html dist/404.htmlFirebase Hostingfirebase.json里配置 rewrites 把所有请求指向/index.html{ hosting: { public: dist, rewrites: [ { source: **, destination: /index.html } ] } }Apache在构建输出目录放一个.htaccess用mod_rewrite把非静态文件请求重写到/index.html文档给出了完整规则要点是RewriteCond %{REQUEST_FILENAME} !-f和!-d两个条件保证真实存在的静态文件优先返回。Cloudflare Pages同样用public/_redirects写/* /index.html 200或用_routes.json控制范围例如排除 API 路径{ version: 1, include: [/*], exclude: [/api/*] }用 TanStack Start SPA mode 时回退目标是/_shell.html如果你的项目是 TanStack Start 且启用了 SPA modetanstackStart({ spa: { enabled: true } })入口文件不是index.html而是构建时预渲染生成的 shell 页面。docs/start/framework/react/guide/spa-mode.md说明默认outputPath是/_shell.html可通过prerender.outputPath配置。回退规则要相应改写Netlify 的_redirects示例# Catch all other 404 requests and rewrite them to the SPA shell /* /_shell.html 200文档强调部署回退的优先级顺序是1静态资源存在时优先返回静态资源多数 CDN 默认行为2可选地把特定子路径放行给服务器3其余 404 请求回退到 SPA shell。如果应用还有 server functions 或 server routes需要先把它们放行再写 catch-all/_serverFn/* /_serverFn/:splat 200 /api/* /api/:splat 200 /* /_shell.html 200如果你自定义了 shell 输出路径把/_shell.html换成实际路径即可。部署在子目录时回退之外还要配 basepathdeploy-to-production.md的 App Works Locally But Breaks When Deployed 一节指出子目录部署时 404/资源加载失败常与 base 配置有关。两处都要对齐Vite 侧vite.config.js中设置base与部署路径一致export default defineConfig({ base: /my-app/, // Match your deployment path })Router 侧RouterOptionsType.md说明basepath用于 mounting a router instance at a subpath即整个 router 的挂载前缀文档示例是basepath: /app。如果 router 内部导航的 URL 没有带前缀而服务器只回退带前缀的请求就会出现导航正常、刷新 404 的错位核对两者是否一致。同一节还提醒两个容易踩的点构建输出目录必须和托管平台的配置一致例如build.outDir: dist要与publish/构建输出目录设置相同环境变量需以VITE_为前缀且修改后要重新构建。验证修复是否生效按deploy-to-production.md的 Production Checklist 和docs/start/framework/react/guide/production-checklist.md的做法验收对每一条路由直接用 URL 访问文档原文要求 Tested all routes by direct URL access而不是从首页点进去再刷新检查静态资源能正常加载样式不丢、JS 不 404Start 的生产检查清单还要求对直接深链单独验证test a direct deep link, a static asset, a server function, and a server route并确认刷新参数化路由和带 search 参数的路由后直访与客户端导航的结果一致。如果回退配置加上后刷新仍 404回头核对三件事回退目标文件路径是否正确index.html还是/_shell.html、托管平台实际使用的构建输出目录、子目录部署时base/basepath是否与回退规则的/*前缀匹配。限制说明以上回退配置针对纯客户端路由SPA / Start SPA mode。deploy-to-production.md明确区分了 TanStack Start SSR 应用Vercel 上要用routes把请求指到/api/serverCloudflare 上要用functions/_middleware.ts处理 SSR 请求不要照抄 SPA 的index.html回退。GitHub Pages 方案依赖404.html复制index.html文档给出的复制时机是构建之后如果你自定义了outDir复制命令中的dist要换成实际目录。本文只覆盖文档明确记录的排查路径文档未涉及的托管平台如其他 CDN 的特定语法不在其中需按平台自己的回退机制实现同一语义静态文件优先其余请求回退到应用入口。主要参考部署指南、路由问题调试、SPA mode、RouterOptionsTypebasepath、生产检查清单。【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考