Motion（包名 motion，前身为 framer-motion）是面向 React 的动画库，提供声明式 API，用较少代码实现复杂动画。资料显示其在生产环境被大量应用使用，GitHub 星标 30,200+，官方示例 300+。
一、主要能力 手势：支持 drag、hover、tap、pan、focus，并具备跨设备支持。 滚动动画：支持视口触发、滚动联动、视差效果。 布局动画：采用 FLIP 技术实现平滑布局变化与共享元素过渡。 弹簧物理：提供自然、可自定义的基于物理的缓动。 SVG：支持路径变形、线条绘制、属性动画。 退出动画：通过 AnimatePresence 实现卸载过渡。 性能：硬件加速、ScrollTimeline API、包体积优化（2.3 KB 至 34 KB）。 生产验证：React 19.2、Next.js 16.1、Vite 7.3、Tailwind v4。
二、适用场景 复杂交互：拖拽界面（可排序列表、看板、滑块）、带缩放/旋转/颜色变化的悬停状态、带弹跳/挤压效果的点击反馈、面向移动端的平移手势。 滚动动画：带视差层的首屏、滚动触发揭示（元素进入视口时淡入）、与滚动位置联动的进度条、随滚动变换的吸顶头部。 布局过渡：路由间共享元素过渡（卡片到详情页）、自动高度动画的展开/折叠、网格/列表视图切换的平滑重排、带动画下划线的标签导航。 高级功能：SVG 线条绘制、形状间路径变形、自然弹跳的弹簧物理、编排序列（交错揭示）、带背景模糊的模态对话框。 包体积优化：需要 2.3 KB 动画库时使用 useAnimate mini；希望将 Motion 从 34 KB 降至 4.6 KB 时使用 LazyMotion。
三、不适用场景 简单列表动画建议改用 auto-animate：待办列表增删（auto-animate 3.28 KB 对比 motion 34 KB）、搜索结果过滤、购物车条目、通知提示、无手势的基础手风琴。 静态内容：无需用户交互或动画、无客户端交互的服务端渲染内容。 3D 动画：应使用专用 3D 库，如 Three.js（WebGL）、React Three Fiber（React + Three.js）。
四、安装与版本 使用 pnpm（推荐）：pnpm add motion 使用 npm：npm install motion 使用 yarn：yarn add motion 当前版本：12.27.5（资料标注验证于 2026-01-21）。 Cloudflare Workers：motion 与 framer-motion 均可使用（问题 #2918 已于 2024 年 12 月修复）。 包信息：完整 motion 组件约 34 KB（压缩+gzip）；LazyMotion + m 组件约 4.6 KB；useAnimate mini 2.3 KB；useAnimate hybrid 17 KB。依赖 React 18+ 或 React 19+，原生支持 TypeScript，无需 @types 包。
五、核心概念 AnimatePresence（退出动画）：用于组件卸载时的动画。关键规则：AnimatePresence 必须保持挂载（不要包在条件内）；所有子元素必须有唯一 key；AnimatePresence 包裹条件，而非被条件包裹。 布局动画：layout 启用 FLIP 布局动画；layoutId 连接不同元素实现共享过渡；layoutScroll 修复可滚动容器中的动画；layoutRoot 修复固定定位元素中的动画。 滚动动画：whileInView 实现视口触发；useScroll 与 useTransform 实现滚动联动。性能上在可用时使用原生 ScrollTimeline API 实现硬件加速。
六、集成方式 Vite + React + TypeScript：pnpm add motion，导入 import { motion } from "motion/react"，无需 Vite 配置。 Next.js App Router：Motion 仅在客户端组件中工作。可创建客户端组件包装（"use client" 配合 import * as motion from "motion/react-client"），再在服务端组件中使用；或直接使用客户端组件。已知问题：AnimatePresence 在软导航时可能失败；Reorder 组件与 Next.js 路由及页面级滚动不兼容。 Next.js Pages Router：无需修改，直接导入使用，无需 "use client"。 Tailwind CSS：Tailwind 负责静态与响应式样式，Motion 负责动画。需移除 Tailwind 的 transition-* 类，否则会卡顿或冲突。 Cloudflare Workers：2024 年 12 月起已支持，直接 pnpm add motion 并导入即可；此前需改用 framer-motion 作为变通，现已解决。
七、性能优化 使用 LazyMotion + m 组件将体积降至 4.6 KB；最小方案 useAnimate mini 为 2.3 KB。 为 transform、opacity、backgroundColor、clipPath、filter 添加 willChange 以启用 GPU 合成。 大型列表（50-100+ 项）使用虚拟化，如 react-window、react-virtuoso、@tanstack/react-virtual。 使用 layout 属性实现 FLIP 动画，通过 transform 硬件加速，避免重排/重绘。
八、无障碍 通过 MotionConfig 的 reducedMotion 属性尊重 prefers-reduced-motion，可选 "user"（推荐）、"always"、"never"。该设置与 AnimatePresence 的配合已于 2023 年 1 月修复。
九、常见模式与已知问题 资料列出 5 个生产可用模式：模态对话框、手风琴、拖拽轮播、滚动揭示、视差首屏，完整代码见 references/common-patterns.md（15+ 模式）。 已知问题包括：AnimatePresence 退出不生效（多因条件包裹或缺少 key，模态内交错子元素定义 exit 也可能阻止卸载）；大列表性能；Tailwind 过渡冲突；Next.js 缺少 "use client"；可滚动容器布局动画需 layoutScroll；Cloudflare Workers 构建错误已解决；固定定位布局动画需 layoutRoot；layoutId 与 AnimatePresence 卸载问题可用 LayoutGroup 包裹或避免混用；Reorder 组件在页面级滚动与 Next.js 路由下存在限制，复杂场景官方推荐 DnD Kit。