在 Next.js App Router…

当需要在 Next.js App Router 或 SPA 路由中为页面切换添加进入/退出动画，或 AnimatePresence 的 exit 动画在导航时不生效时使用。

适用场景

解决思路

1. 方案 A：在 app/template.tsx 中放置 AnimatePresence（template 每次导航都会重新挂载，而 layout 会持久化），用 usePathname() 作为 key，并用 FrozenRouter 包裹 children，使退出中的旧页面继续渲染旧内容。
2. 在 PageTransition 组件中用 motion.div 定义 initial/animate/exit（例如 opacity 与 y 位移），transition 时长约 0.3s、使用 ease-out 曲线。
3. 实现 FrozenRouter：用 useContext 读取 LayoutRouterContext，用 useRef(context).current 冻结该 context，再通过 LayoutRouterContext.Provider 传下去，让退出的子树在动画期间渲染上一路由的内容。
4. AnimatePresence 使用 mode="wait" 让退出动画完全结束后再挂载新页面；若希望进出重叠/交叉淡入淡出则使用默认 mode。
5. 设置 initial={false} 跳过首次加载时的进入动画（可选）。
6. 注意 LayoutRouterContext 是 Next.js 内部 API，其导入路径可能随版本变化，升级后若报错需更新该路径。
7. 方案 B：使用原生 View Transitions API，在 globals.css 中写 @view-transition { navigation: auto; } 以及 ::view-transition-old(root)/::view-transition-new(root) 的 fade 关键帧动画。
8. 对于 SPA 式导航，用 if (document.startViewTransition) { document.startViewTransition(() => router.push(href)); } else { router.push(href); } 包裹路由更新，并提供降级回退。
9. 使用 next-view-transitions 库：在 app/layout.tsx 中用 <ViewTransitions> 包裹 html/body，并把 next/link 替换为该库的 Link 组件。
10. 选择依据：简单跨页淡入淡出/形变和共享元素过渡用 View Transitions；需要细粒度、可编排、可中断或错峰退出动画时用 Framer Motion。
11. AnimatePresence 退出不触发时的排查清单：1) 确认 AnimatePresence 位于持久挂载的组件中（如 template.tsx 或布局级客户端组件），而非正在卸载的页面内；2) 动画子元素必须有随路由变化的稳定 key（如 key={pathname}）；3) 带 exit 的元素必须是 motion.* 组件且为 AnimatePresence 的直接子元素，中间不能有非 motion 包装层；4) 若新旧页面不应重叠则设置 mode="wait"；5) 若退出时闪现新路由内容则加入 FrozenRouter；6) 所有使用 AnimatePresence/usePathname/motion 的文件都要加 'use client'；7) mode="wait" 下同一时刻只保留一个带 key 的子元素。
12. 用独立 HTML 文件验证过渡形态：两个视图桩 + 切换按钮，用 CDN 的 motion/React 或 document.startViewTransition + ::view-transition-* CSS 实现动画。
13. 用 ?view=b 挂载目标视图、?phase=exit 保持退出中的树，使截图落在确定的过渡阶段；View Transitions 需截取结束状态（快照是瞬时的），或通过模拟慢速动画暂停。
14. 验证循环：分别打开源、中间、目标状态（?view=a、?phase=exit、?view=b）截图，检查保真度（退出确实执行、方向/交叉淡入淡出符合预期、mode="wait" 无卡顿）与瑕疵（旧树闪现新页面内容、重复挂载、FOUC、卡顿）。可用 npx playwright screenshot --wait-for-timeout=500 "file://$PWD/transition.html?view=b" dest.png。
15. 完成前检查：1) 可独立打开、无控制台错误、CDN 依赖可解析、startViewTransition 有守卫；2) ?view=/?phase= 冻结能得到确定的过渡阶段；3) 源/中间/目标三处截图符合预期，无内容闪烁或退出被跳过；4) 尊重 prefers-reduced-motion，将滑动/位移降级为短交叉淡入淡出；5) 缓动有意为之——进入用 ease-out、退出用 ease-in，时长约 0.2–0.4s（避免 mode="wait" 下显得卡顿）。

适用边界 · 注意事项

• layout.tsx 会持久化、不会随路由重新挂载，因此不能用于每路由的进入动画，应改用 template.tsx。
• View Transitions API 浏览器支持尚不完整，不能无条件使用，必须用 if (document.startViewTransition) 守卫并提供回退。
• 服务端组件无法使用 AnimatePresence/usePathname，相关文件必须加 'use client'。