Framer Motion (Motion)

React 生态最流行的声明式动画库，以简洁的 API 驱动布局动画、手势交互和退出动画，2024 年底从 Framer 独立并更名为 Motion，现已支持 React、Vue 和纯 JavaScript 环境。

技术简介说明

Motion（前身为 Framer Motion）由 Matt Perry 于 2018 年创建，最初作为 Framer 设计工具的配套动画库发布。Matt Perry 此前已有十年动画库开发经验，早在 2014 年就创建了 Popmotion 动画引擎。Framer Motion 凭借声明式的 motion 组件、内置弹簧物理引擎和 AnimatePresence 退出动画等特性，迅速成为 React 生态最受欢迎的动画方案，被 Figma、Framer 等数百万用户的产品所采用。

2024 年 11 月，Motion 正式从 Framer 独立出来，品牌名从 "Framer Motion" 简化为 "Motion"，npm 包名从 framer-motion 迁移至 motion，导入路径改为 motion/react。这次独立意味着 Motion 不再局限于 React——它现在支持 React、Vue 和纯 JavaScript 环境，同时保持与旧包的完全兼容（framer-motion 包仍然可用且持续同步更新）。

Motion 采用混合动画引擎架构：优先使用 Web Animations API（WAAPI）和 ScrollTimeline 等浏览器原生能力实现 GPU 加速渲染，在需要弹簧物理、手势追踪等高级特性时无缝回退到 JavaScript 驱动。全库以 TypeScript 编写，支持 tree-shaking，最小核心仅 2.6 KB，完整版约 18 KB gzipped，远低于同类竞品。

基本信息

• 官网：https://motion.dev
• GitHub：https://github.com/motiondivision/motion（32.7k stars，1.2k forks，144 contributors）
• License：MIT（完全开源，支持商业用途）
• 最新版本：12.42.2（2026 年 7 月 1 日发布）
• npm 周下载量：motion 约 1300 万+，framer-motion 约 3350 万+（合计约 4650 万/周，2026 年 7 月数据）
• 包体积：mini 版 ~2.6 KB / 完整版 ~18 KB gzipped
• 主要维护者/公司：Matt Perry（Motion Division），2024 年 11 月前由 Framer 支持
• 语言：TypeScript（72.8%）、HTML（21.9%）、JavaScript（5.0%）
• 框架支持：React 18.2+、Vue、纯 JavaScript
• 浏览器支持：所有现代浏览器（Chrome、Firefox、Safari、Edge）

快速上手

安装

NPM / Yarn / pnpm

# npm（推荐）
npm install motion
 
# yarn
yarn add motion
 
# pnpm
pnpm add motion

注意：旧包名 framer-motion 仍然可用且代码完全相同，但新项目推荐使用 motion。从 framer-motion 迁移只需卸载旧包、安装新包并更新导入路径。

CDN

<script type="module">
  import { motion } from "https://cdn.jsdelivr.net/npm/motion/+esm"
</script>

基础配置

标准 React / Vite 项目

无需额外配置，安装后即可使用：

import { motion } from "motion/react"

Next.js（App Router）

由于 Motion 组件依赖浏览器 API，在 Next.js App Router 中需要标记为客户端组件：

"use client"
import { motion } from "motion/react"
 
export default function Page() {
  return <motion.div>内容</motion.div>
}

如需减小客户端 JS 体积，可使用精简导入路径 motion/react-client（去除服务端不需要的功能）。

TypeScript

Motion 自带完整的 TypeScript 类型定义，无需额外安装 @types 包。

最小示例

import { motion } from "motion/react"
 
export default function App() {
  return (
    <motion.div
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.5 }}
    >
      Hello Motion!
    </motion.div>
  )
}

上述代码将一个普通 div 转换为动画组件，元素挂载时从透明、下移 20px 的位置平滑淡入到正常位置。

核心概念与架构

Motion 组件

motion 是 Motion 的核心原语。通过为任意 HTML 或 SVG 元素添加 motion. 前缀（如 motion.div、motion.svg、motion.path），即可解锁声明式动画属性：initial（初始状态）、animate（目标状态）、exit（退出状态）、whileHover、whileTap、whileDrag、whileInView 等。

混合动画引擎

Motion 采用混合渲染策略：优先使用 Web Animations API（WAAPI）和 ScrollTimeline 等浏览器原生接口实现 GPU 加速动画（可达 120fps），在需要弹簧物理、手势追踪、布局动画等高级能力时无缝回退到 JavaScript requestAnimationFrame 驱动。这种架构在性能和功能覆盖之间取得了最佳平衡。

Variants（变体）

Variants 是命名动画状态的对象，支持在组件树中传播和编排。通过 variants 属性定义命名状态，子组件可继承父组件的变体并实现错开动画（stagger）。结合时间线（Timeline）API，可以编排复杂的多段动画序列。

AnimatePresence

<AnimatePresence> 组件监听子元素的挂载/卸载，使元素离开 DOM 时也能执行退出动画（通过 exit 属性定义）。这是 React 生态中实现退出动画的标准方案。

Layout Animations（布局动画）

添加 layout 属性后，Motion 会自动检测元素位置和尺寸变化并执行平滑过渡。layoutId 属性可实现跨组件的共享布局动画（类似 Hero 动画），Motion 会自动修正缩放导致的视觉变形。

Gesture System（手势系统）

内置 hover、press、drag 等手势支持，通过 whileHover、whileTap、whileDrag 等声明式属性绑定，底层处理了触摸、鼠标、指针事件的兼容性，支持键盘导航。

MotionValue

useMotionValue 提供响应式的动画值追踪，可驱动派生状态（useTransform）、组合多个值、实时读取动画进度，是连接动画系统与 React 状态的桥梁。

架构设计

┌─────────────────────────────────────────────────┐
│              motion/react (React 层)             │
│  motion 组件 / AnimatePresence / useScroll 等    │
├─────────────────────────────────────────────────┤
│              motion (核心引擎层)                  │
│  动画状态机 / Variants / Timeline / Gesture      │
├─────────────────────────────────────────────────┤
│              渲染后端                             │
│  WAAPI（优先）←→ rAF（回退）/ ScrollTimeline      │
└─────────────────────────────────────────────────┘

核心特性

• 声明式动画 API：通过 initial、animate、exit 等属性直接描述动画状态，无需手动管理生命周期
• 弹簧物理引擎：使用真实弹簧数学模型（非近似），默认用于物理属性动画，可自定义质量、刚度、阻尼
• 布局动画：单个 layout 属性即可实现位置/尺寸的自动平滑过渡，layoutId 支持跨组件共享动画
• 退出动画：<AnimatePresence> 原生支持组件卸载时的退出动画，React 生态中的标准方案
• 手势交互：内置 hover、press、drag、scroll 等手势，自动处理触摸/鼠标/指针事件兼容
• 硬件加速渲染：混合使用 WAAPI 和 ScrollTimeline，GPU 加速动画可达 120fps
• SVG 动画：原生支持 SVG 属性动画，包括 viewBox、pathLength 路径绘制效果
• 滚动触发动画：whileInView 和 useScroll 实现元素进入视口时的动画和滚动进度绑定
• Variants 与编排：命名动画状态、错开动画（stagger）、Timeline 时间线编排复杂序列
• Tree-shaking 支持：完全模块化设计，最小核心仅 2.6 KB
• TypeScript 原生：全库 TypeScript 编写，完整的类型推导，无需额外类型包
• 跨框架支持：从 React 专用扩展为支持 React、Vue 和纯 JavaScript 的通用动画库
• AI 工具集成：与 Cursor 合作支持 AI 一键生成动画组件，提供 AI Kit 辅助动画开发

生态图

生态系统概览

Motion 围绕核心动画引擎构建了完整的生态系统：

关键依赖

Motion 本身零外部运行时依赖，仅依赖浏览器原生 API（WAAPI、ScrollTimeline、requestAnimationFrame）。开发时需要 React 18.2+（React 项目）。

与 Framer 的关系

Motion 最初是 Framer 设计工具的内置动画引擎。2024 年 11 月独立后，Motion 成为独立的开源项目，Framer 仍作为 Motion 的重要用户和合作伙伴。Framer 网站仍然使用 Motion 作为底层动画引擎。

社区生态

• npm 合计周下载量超 4650 万（2026 年 7 月），是 React 动画领域的绝对主流
• GitHub 32.7k stars，144 位贡献者，7772 次提交
• 与 Cursor AI 编辑器深度合作，支持 AI 驱动动画组件生成
• 大量教程、博客和第三方组件生态

适用场景

• React 应用 UI 动画：淡入淡出、滑入滑出、缩放等组件级过渡动画，Motion 的声明式 API 和 AnimatePresence 使其成为 React 项目的首选
• 页面路由过渡：结合 AnimatePresence 实现页面切换时的进入/退出动画，Next.js 和 React Router 项目中的标准方案
• 布局动画与排序过渡：列表重排、筛选、折叠/展开时自动平滑过渡，单个 layout 属性即可实现
• 滚动叙事与视差：whileInView 和 useScroll 实现滚动触发动画、视差效果和进度绑定动画
• 手势交互反馈：拖拽排序、hover 反馈、按压动画等微交互，内置手势系统无需额外库
• 共享元素过渡（Hero 动画）：layoutId 实现跨组件/跨页面的共享元素平滑过渡
• 数据可视化动画：SVG 路径绘制、数值过渡、图表动画等

开发与工程化

开发流程

1. 安装与导入：安装 motion，从 motion/react 导入所需组件和 hooks
2. 组件化动画：将动画逻辑封装为可复用的 motion 组件，使用 Variants 定义动画状态
3. 性能审计：使用 MotionScore 或浏览器 DevTools Performance 面板检测动画帧率
4. 测试：Motion 组件可在 Jest / Vitest 中测试，注意初始挂载通过 microtask 调度，断言样式需等待下一帧

构建部署

• Tree-shaking：Motion 完全支持 ES Module tree-shaking，仅打包实际使用的功能
• Next.js 优化：App Router 中使用 motion/react-client 精简导入路径，减少客户端 JS 体积
• SSR 兼容：Motion 支持服务端渲染，动画在客户端水合后执行
• Code Splitting：动画组件可按路由或功能懒加载

工程化最佳实践

• 优先使用 transform 和 opacity 属性动画（GPU 加速）
• 复杂动画状态抽取为 Variants 对象，集中管理
• 列表动画使用 layout + layoutId 而非手动计算位置
• 使用 useMotionValue + useTransform 构建派生动画状态
• 生产环境使用 process.env.NODE_ENV 检查确保开发时警告不进入生产包

性能与安全

性能特点

• 混合渲染引擎：优先使用 WAAPI / ScrollTimeline 实现 GPU 加速，JavaScript 回退确保功能完整
• 120fps 支持：在高刷新率设备上可平滑运行 120fps 动画
• 最小体积：mini 核心 2.6 KB，完整版 18 KB gzipped，显著低于 GSAP（23.5 KB+）
• 批量样式计算：合并多次样式更新为单次 DOM 写入，减少重排
• 模块化加载：按需导入，未使用的功能不会被打包

性能优化建议

• 优先动画 transform（translate、scale、rotate）和 opacity，避免动画 width、height、top、left 等触发重排的属性
• 使用 willChange 提示浏览器提前优化（Motion 部分场景会自动处理）
• 大量列表动画时考虑虚拟化（结合 react-window 等），避免同时渲染过多动画节点
• 使用 layout 属性时注意 FLIP 测量的开销，复杂布局场景做性能测试
• 避免在动画回调中触发 React 状态更新导致额外渲染

安全注意事项

• Motion 不涉及用户输入处理或网络请求，无特殊安全风险
• 使用 dangerouslySetInnerHTML 结合 Motion 动画时仍需注意 XSS 风险（与 Motion 无关，属通用 React 安全原则）
• MIT 开源许可，无许可证风险

技术对比

选择建议：

• React / Next.js 项目首选 Motion：声明式 API、退出动画、布局动画、手势支持一站式解决
• 复杂跨框架动画 / 极致滚动叙事选 GSAP：时间线编排和 ScrollTrigger 仍是行业标杆
• 极简弹簧动画选 React Spring：轻量且专注，但社区活跃度已落后于 Motion
• 简单过渡且不想引入依赖选 CSS 动画：零成本但功能有限

最佳实践

生产环境建议

1. 新项目使用 motion 包：安装 motion 并从 motion/react 导入，而非旧的 framer-motion
2. Next.js App Router：添加 "use client" 指令，或使用 motion/react-client 精简体积
3. 封装动画组件：将常用动画模式封装为可复用组件，避免在业务代码中重复配置
4. Variants 集中管理：复杂动画状态使用 Variants 对象定义，便于维护和测试
5. 性能优先 GPU 属性：优先动画 transform 和 opacity，避免触发重排的属性
6. 合理设置 layout 范围：layout 属性会触发 FLIP 测量，仅在需要时添加
7. 测试等待微任务：Motion 组件初始挂载通过 microtask 调度，测试中需等待下一帧再断言样式

常见陷阱

• 忘记 "use client"：Next.js App Router 中使用 Motion 组件必须标记为客户端组件
• AnimatePresence 需要 key：子元素必须有唯一的 key 属性，否则退出动画不会触发
• layout 与绝对定位冲突：layout 动画可能与某些 CSS 定位方案冲突，需测试验证
• 弹簧参数调优：默认弹簧参数不一定适合所有场景，过大的刚度或过小的阻尼会导致抖动
• 过度使用布局动画：大型列表中使用 layout 可能带来性能开销，需结合虚拟化

推荐模式

// 模式1：Variants 集中定义动画状态
const container = {
  hidden: { opacity: 0 },
  show: {
    opacity: 1,
    transition: { staggerChildren: 0.1 }
  }
}
 
const item = {
  hidden: { opacity: 0, y: 20 },
  show: { opacity: 1, y: 0 }
}
 
// 模式2：封装可复用动画组件
function FadeIn({ children, ...props }) {
  return (
    <motion.div
      initial={{ opacity: 0, y: 10 }}
      whileInView={{ opacity: 1, y: 0 }}
      viewport={{ once: true }}
      {...props}
    >
      {children}
    </motion.div>
  )
}
 
// 模式3：MotionValue 派生状态
const x = useMotionValue(0)
const opacity = useTransform(x, [-100, 0, 100], [0, 1, 0])

技术局限与边界

已知限制

• React 版本要求：最低 React 18.2，不支持 React 17 及以下（v7 起）
• IE 不支持：无 IE 浏览器支持，依赖现代浏览器 API
• 服务端动画受限：SSR 时动画不执行，仅客户端水合后生效
• 布局动画开销：layout 属性触发 FLIP 测量，大型复杂布局可能有性能开销
• 无逆向播放：不支持 GSAP 的反向播放（reverse）功能
• 时间线为静态数组：不像 GSAP 时间线可在播放后动态修改，Motion 时间线是预定义的

不适用场景

• 极度复杂的动画编排：如需精细控制数百个时间线节点和逆向播放，GSAP 更合适
• Canvas / WebGL 动画：Motion 专注 DOM/SVG，Canvas 动画应使用 PixiJS、Three.js 等
• 非 Web 环境：不支持 React Native（需使用 react-native-reanimated）、iOS/Android 原生
• 零依赖要求：即使是 2.6 KB 也有体积成本，极简单动画用 CSS 更合适

品牌更名迁移注意事项

从 framer-motion 迁移到 motion 的步骤：

# 1. 卸载旧包
npm uninstall framer-motion
 
# 2. 安装新包
npm install motion

// 3. 更新导入路径
// 旧：
import { motion, AnimatePresence } from "framer-motion"
// 新：
import { motion, AnimatePresence } from "motion/react"

注意事项：

• framer-motion 包未被废弃，仍会持续同步更新，无紧急迁移压力
• API 基本保持不变，主要变更是导入路径
• 部分旧版 API 已重命名：easing → ease，direction → repeatType，endDelay 已移除（改用 repeatDelay）
• 3D 功能已独立为 framer-motion-3d 包

学习资源

官方文档

• Motion 官网 — 首页与概览
• Motion for React 文档 — React 完整 API 文档
• React 动画指南 — 关键帧、过渡、手势详解
• React 安装指南 — 安装与框架配置
• 升级指南 — 从 Framer Motion 迁移到 Motion
• Changelog — 版本更新日志
• 独立公告 — 品牌更名官方说明
• GSAP vs Motion 对比 — 官方对比文档

教程

• Framer Motion Tutorial: Build Stunning React Animations in 2026 — 2026 年完整教程
• Framer Motion React Animations: Complete Guide — Refine 出品完整指南
• React Animation Course with Motion — YouTube 视频课程
• Matt Perry - Web Animation with Motion — 作者亲自讲解

社区资源

• GitHub Issues — 问题反馈与讨论
• Reddit r/reactjs 讨论 — 社区对品牌更名的讨论
• PodRocket: Framer Motion and Motion One with Matt Perry — 作者访谈播客
• DevTools FM Episode 124 — 深度技术访谈
• Spell UI: 15 Best React Animation Libraries Compared (2026) — 2026 横评
• LogRocket: Comparing the best React animation libraries for 2026 — 2026 对比评测

2026 年现状

最新版本

• Motion 12.42.2（2026 年 7 月 1 日）：持续活跃迭代，最近 6 个月内发布了 20+ 个版本
• Motion+ 2.12.0（2026 年 6 月 9 日）：高级付费功能持续更新
• Motion AI Kit 6.1.0（2026 年 5 月 28 日）：AI 辅助动画工具快速迭代

发展趋势

• 品牌独立化完成：从 Framer 独立后，Motion 已建立完整的独立品牌、文档和生态
• 跨框架扩展：从 React 专用扩展为支持 React、Vue 和纯 JavaScript，用户群持续扩大
• AI 集成：与 Cursor 合作推出 AI Kit，支持 AI 一键生成动画组件，顺应 AI 辅助开发趋势
• 性能持续优化：AnimateNumber 等组件改用手动 FLIP 测量替代布局动画，持续降低开销
• React 19 兼容：已完成 React 19 兼容适配，支持 Next.js 15

社区活跃度

• GitHub：32.7k stars，144 contributors，7772 commits，107 open issues，活跃维护
• npm 下载量：motion + framer-motion 合计约 4650 万/周，是 React 动画领域的绝对领导者
• 增长趋势：从 2023 年的约 170 万/周增长到 2026 年的 4650 万+/周，增长超 27 倍
• 对比 GSAP：Motion 合计下载量约为 GSAP（350 万/周）的 13 倍

品牌更名影响

• framer-motion 仍占下载量的大头（约 3350 万/周），说明大量项目尚未迁移
• motion 新包增长迅速（约 1300 万/周），新项目普遍采用新包名
• 两个包代码完全相同，社区对更名接受度高，无重大迁移摩擦
• 旧教程和博客仍大量使用 "Framer Motion" 名称，搜索引擎中两个名称并存