HTML5History 返回白屏的典型原因
不是路由没注册，也不是 history.pushState 失效，而是页面刷新或返回时，服务端没正确响应静态资源路径，导致 HTML 文件没加载成功——浏览器拿到的是 404 或空响应，自然白屏。
常见错误现象：Failed to load resource: the server responded with a status of 404 ()，但控制台没报 JS 错误；地址栏显示 /user/profile，Network 面板里却在请求这个路径的 HTML。
- 前端用
createWebHistory（Vue Router）或createBrowserHistory（React Router v6）时，依赖服务端对所有前端路由返回同一份index.html - 开发环境（Vite / Webpack Dev Server）默认做了 fallback，所以本地不白屏；一上 Nginx / Express 就暴露问题
- 若用 GitHub Pages、Vercel、Netlify 等托管，需显式配置重写规则，不能只靠
404.html
Nginx 下 history 路由 fallback 配置要点
核心就一条：把所有非静态资源请求（即不匹配 .js、.css、.png 等后缀的请求），全部 rewrite 到 /index.html，且不中断后续匹配。
容易踩的坑：try_files $uri $uri/ /index.html; 看似简洁，但会把 /api/user 这类真实接口也兜底到 index.html，造成 API 404。
立即学习“前端免费学习笔记（深入）”；
- 优先判断是否为真实静态文件：
if (!-e $request_filename) { ... }不推荐，Nginx 官方明确反对在 location 中用if - 正确做法是用
location块精准排除静态资源路径：location ^~ /static/、location ~* \.(js|css|png|jpg|gif|ico)$ - 兜底 location 必须加
= 404检查，避免无限循环：location / { try_files $uri $uri/ /index.html; }是安全的
popstate 事件监听失效的三个常见条件
popstate 不是“只要用了 history.pushState 就自动触发”，它只在用户点击浏览器前进/后退按钮，或调用 history.back()、history.go() 时触发。手动改 URL（如 location.hash）或直接赋值 location.href 不会触发。
常见错误现象：页面能跳转，但返回时不执行任何逻辑，useEffect(() => { window.addEventListener('popstate', handler) }, []) 没反应。
- 监听必须在组件挂载后立即绑定，且不能依赖未初始化的 state ——
handler里读取的router.currentRoute可能还是旧值 - Vue Router 3 的
router.afterEach和 Vue Router 4 的router.beforeEach已覆盖大部分场景，无需手动监听popstate - 如果真要监听，务必用
addEventListener+removeEventListener配对，否则热更新或多次挂载会导致重复绑定
路由守卫中 next() 不执行的隐性陷阱
守卫函数里漏写 next()，或写了但参数非法（比如传了不存在的路由名），会导致导航停滞——看起来像卡住，实际是路由没提交，router.currentRoute 仍为上一个值。
Vue Router 的 beforeEach 和 React Router 的 useNavigate + createRouter 的守卫逻辑不同，但共性问题是“控制流中断”。
-
next(false)会中止导航，但不会报错；next('/login')是合法跳转，而next({ name: 'NotFound' })若该命名路由未定义，就静默失败 - 异步守卫中，
await api.checkAuth()后忘记next()，比同步场景更难排查 - 不要在守卫里直接修改
to.meta并期望它影响后续逻辑——meta 是只读的，得靠to.matched[0].meta手动判断
最麻烦的其实是组合场景：Nginx 配置对了，但某个子应用用了 iframe 加载，父页面的 popstate 监听被隔离；或者守卫里调了接口，接口返回 302 重定向，导致 history 栈多了一层又没清理。这些没法靠单一配置解决，得一层层确认执行上下文。
