nextjs-framer-motion-animations

Next.js 中有目的的动效

选择动效来说明状态或改善交互，而不是给每个页面都增加一层动效。保留现有设计令牌和语义化控件。对于简单的颜色、焦点或悬停过渡，使用 CSS 或许可以避免不必要的客户端 JavaScript。

先检查，再确定边界

阅读实际组件、路由器（App 或 Pages）、package/lockfiles、已安装的 Motion API 和构建配置。确定由谁负责挂载、状态、焦点、滚动和导航。区分局部显示与路由过渡。文件名或令牌扫描器无法证明这些关系或构建兼容性。

对于现代化改造或新编写的 Motion 代码，使用 motion/react。在 Server Component 中，受支持的 motion/react-client 入口会提供 motion 元素；它不会让 hooks 或任意回调变得可在服务端安全使用。将交互逻辑和 hooks 放在尽可能小的 Client Component 中，同时让数据获取和机密留在服务端。服务端渲染的子元素可以通过客户端包装器传递，而无需将其实现移入客户端包。跨越该边界的 props 必须符合 React 实际的序列化约定。

对于现有的 framer-motion 项目，检查其已安装版本，并决定是否将迁移纳入范围。有计划的迁移应一并更新 package、imports、lockfile、tests 以及任何发生变化的 API。不要混用运行时，也不要通过机械替换，将来自 motion/react-m 的命名空间导入改写为其他模块。此技能不附带兼容分支或自动导入改写功能。

选择实现方式

需求	从这里开始	必要条件
简单的局部补间动画／手势	motion element	保留语义化元素以及禁用／焦点行为
多个协同的子元素	variants 和 stagger	身份稳定，延迟总时长有上限
局部移除	AnimatePresence	它能在带 key 的子元素移除后继续存在并观察该元素
布局变化	layout / layout="position"	测量正确且身份得以保留
活动树中的共享元素	layoutId / LayoutGroup	ID 唯一且作用范围明确
可见性显示	whileInView	滚动根节点正确，且可渐进显示
与滚动关联的值	useScroll 加 motion values	目标／容器正确，且制定减少动效策略
命令式序列	useAnimate	目标范围明确，并能取消／清理
对包体积敏感的区域	LazyMotion 和 m	功能集涵盖所用的布局／拖拽 API
路由／共享视图过渡	框架支持的 ViewTransition	符合实际的 Next／React／浏览器约定，而不是路径名包装器

请阅读组件模式，了解实现决策；阅读路由器集成，了解路由变化。不要假定整个包只需一个 provider，或每种交互都适合相同的动画时长。

Presence 与应用状态

要让自身退出动画生效，AnimatePresence 必须持续存在；但要控制由路由器管理的子树，仅靠它并不足够。按路径名给包装器设置 key，并不能保证离开的路由内容会原样保留。不要冻结私有路由器上下文、拦截所有点击，或延迟所有导航来让退出动画演示正常运行。请使用受支持的框架路由机制，或如实实现仅增强进入效果。

动画回调不是事务边界。不要让付款、删除、导航确认或其他应用结果取决于动画是否恰好完成。取消、中断、重新挂载和减少动效都必须保留相同的逻辑结果。

无障碍与渲染

在适合现有组件树的位置使用 MotionConfig reducedMotion="user"，并针对滚动、自动播放和定制效果，在局部使用 useReducedMotion 做出决策。仅透明度动画以及独立的 CSS／视图过渡路径需要各自的策略；一个 Motion 提供器并不能统一控制所有动画。

使用真正的按钮／链接／对话框。保留键盘操作路径、可见的焦点、符合逻辑的阅读顺序，以及拖动操作的等效替代方式。退出时已不可见的控件不得继续获得焦点或拦截输入。视觉上的模态框外壳并不等于焦点管理、Escape 键行为、标签或背景惰性处理。

不要在服务端渲染时让关键文本一直不可见，并依赖成功的水合／交叉观察器来显示文本。在必要时保持布局框稳定，并处理字体／图片加载、视口变化，以及无 JavaScript／失败时的行为。适合时使用变换／透明度，但在声称性能有所提升前，先衡量实际的绘制、布局、合成和包体成本。

验证实际改动

在获得授权的情况下，运行项目现有的类型检查／lint／构建流程；不要假设其脚本名称是 npm run lint/build。在浏览器中测试快速交互、前进／后退导航、缓慢的数据加载、中断、减少动态效果设置、键盘操作，以及共享布局组件的多个副本。检查控制台／水合错误、滚动位置恢复、焦点和可用的非动画回退方案。单元测试模拟并不能替代浏览器性能或路由器生命周期测试。

交付补丁、所选边界／机制、实际验证结果以及尚需进行的浏览器检查。旧的通用扫描器、生成的计划、全资源脚手架及其黄金输出包均已移除；目标是提供真实的集成证据，而非复现某种启发式方法偏好的输出。

资料来源与维护

审核日期：2026-09-13：Motion 安装、AnimatePresence、Next 模板和 Next 视图过渡。 评估用例描述了必需的检查项，并非已运行的测试。