react-spring 移除废弃渲染目标与 umbrella 包：从@react-spring/web/@react-spring/three直装的迁移指南
【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring
本篇指南基于本仓库 .changeset/remove-deprecated-targets.md 中记录的破坏性变更（breaking change）展开：react-spring 的
next主分支已正式移除被标记为废弃的@react-spring/native、@react-spring/konva、@react-spring/zdog三个渲染目标及其 React Native Hook 变体，同时移除了react-spring伞形（umbrella）包。文章将结合仓库内真实的 package 结构与源码（packages/core、targets/web、targets/three、docs/app/routes/docs.getting-started.mdx等）说明迁移路径：直接安装@react-spring/web或@react-spring/three作为目标包，并针对 React Native 场景给出官方推荐的替代方案（Reanimated，其 spring 运行在 UI 线程而非 react-spring 的 JS 线程引擎）。
变更一览：这是一次major级别的破坏性变更
该 changeset 位于 .changeset/remove-deprecated-targets.md，frontmatter 声明：
--- '@react-spring/web': major ---即该变更只以@react-spring/web为发布锚点、按major（主版本号）发布。注意，由于仓库根目录的 .changeset/config.json 配置了：
"fixed": [["@react-spring/*"]]所有@react-spring/*包会被固定为一组、同步提升主版本，因此这次移除废弃目标与 umbrella 包的动作实际上影响整个@react-spring/*发布组。变更的具体内容：
- 移除废弃的渲染目标：
@react-spring/native、@react-spring/konva、@react-spring/zdog三个包被删除； - 移除对应的 React Native Hook 变体（如
useSpring、useSprings、useTrail、useTransition在 native 目标下的导出）； - 移除
react-springumbrella 包（旧版本中用于统一转发到具体目标包的一层壳）； - 明确替代方式：直接安装目标包 ——
@react-spring/web或@react-spring/three； - React Native 用户：改用 Reanimated（官方文档见 changeset 中的链接，仓库内不携带），其 spring 运行在 UI 线程，而 react-spring 的引擎运行在 JS 线程。
从仓库当前目录结构看，targets/下仅保留 targets/web/ 与 targets/three/ 两个目标包，packages/下保留animated、core、shared、types、rafz等核心与工具包，与变更声明完全一致。
为什么会有「目标包」与「umbrella 包」之分？
react-spring 采用「核心引擎 + 渲染目标」的分层架构：
- 核心与工具包（平台无关）：
- packages/core/：
@react-spring/core，Spring 物理引擎、useSpring/useSprings/useTrail/useTransition等 Hook、Controller/SpringValue等核心类。其入口 packages/core/src/index.ts 统一导出 hooks、components、interpolate、Controller、SpringValue、SpringContext、SpringRef、FrameValue、Interpolation等； - packages/animated/：
@react-spring/animated，将 Spring 值映射到具体渲染层的适配层（Animated/AnimatedValue/createHost等）； - packages/shared/、packages/types/、packages/rafz/：工具函数、类型定义与 raf 调度。
- packages/core/：
- 渲染目标包（绑定具体平台）：
- targets/web/：
@react-spring/web，其入口 targets/web/src/index.ts 通过createHost(primitives, ...)构建animated组件，并export * from '@react-spring/core'把核心 API 一并转发出去； - targets/three/：
@react-spring/three，面向 react-three-fiber / three.js 场景。
- targets/web/：
因此用户通常只需要安装一个目标包即可拿到完整 API。而旧版本中额外的react-springumbrella 包只是再包一层转发，除了让import { useSpring } from 'react-spring'的写法成立之外，并没有提供额外能力，反而带来多包维护与版本对齐成本 —— 这正是本次将其移除的动机。
迁移指南：从安装/导入层面直装目标包
第一步：更新安装命令
删除对废弃包的引用，改为直接安装目标包：
# 旧写法（已移除，勿再使用） # npm install react-spring # npm install @react-spring/native @react-spring/konva @react-spring/zdog # 新写法：按你的渲染平台选择 npm install @react-spring/web # Web (DOM / CSS / SVG / HTML) npm install @react-spring/three # three.js / @react-three/fiber使用 Yarn 或 pnpm 时同理：
yarn add @react-spring/web # 或 pnpm add @react-spring/three当前仓库内各包的package.json已统一为 ESM-only（见 .changeset/esm-only.md 与 targets/web/package.json 中的"type": "module"与"exports"字段），并在 package.json 中声明"packageManager": "pnpm@9.15.9"、"engines": { "node": ">=24.16.0" }，请确保包管理器与 Node 版本满足要求。
第二步：修改 import 语句
- Web 项目：
import { useSpring, animated } from 'react-spring'→import { useSpring, animated } from '@react-spring/web' - Three.js 项目：
import { useSpring } from 'react-spring/three'→import { useSpring, animated } from '@react-spring/three' - 任何
from '@react-spring/native'、from '@react-spring/konva'、from '@react-spring/zdog'的导入均需删除或替换。
以仓库官方入门文档 docs/app/routes/docs.getting-started.mdx 为准，Web 侧的标准用法如下：
import { useSpring, animated } from '@react-spring/web' export default function MyComponent() { const springs = useSpring({ from: { x: 0 }, to: { x: 100 }, }) return ( <animated.div style={{ width: 80, height: 80, background: '#ff6d6d', borderRadius: 8, ...springs, }} /> ) }注意：animated必须来自目标包（@react-spring/web导出animated及其别名a，见 targets/web/src/index.ts），而useSpring等核心 Hook 通过export * from '@react-spring/core'一并可用，用户无需关心核心包细节。
第三步：检查package.json依赖清单
在dependencies中删除：
"react-spring": "...", "@react-spring/native": "...", "@react-spring/konva": "...", "@react-spring/zdog": "..."保留或新增（按平台二选一）：
{ "dependencies": { "@react-spring/web": "^11.0.0", "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }目标包对 React 的 peer 依赖可见 targets/web/package.json（支持 React 16.8 及以上，含 19）；@react-spring/three则额外要求@react-three/fiber >= 6.0与three >= 0.126，见 targets/three/package.json。
迁移示例：从 umbrella 到@react-spring/web
迁移前（已废弃写法）：
import { useSpring, animated } from 'react-spring' export default function Card() { const props = useSpring({ from: { opacity: 0, transform: 'translateY(20px)' }, to: { opacity: 1, transform: 'translateY(0px)' }, }) return <animated.div style={props}>Hello</animated.div> }迁移后：
import { useSpring, animated } from '@react-spring/web' export default function Card() { const props = useSpring({ from: { opacity: 0, transform: 'translateY(20px)' }, to: { opacity: 1, transform: 'translateY(0px)' }, }) return <animated.div style={props}>Hello</animated.div> }除 import 来源外，API 形态完全不变 —— 这正是移除 umbrella 包对用户影响最小的原因。仓库 demo 目录下所有沙箱示例（如 demo/src/sandboxes/simple-transition/src/App.tsx、demo/src/sandboxes/trail/src/App.tsx 等）均已统一从@react-spring/web导入，可作为迁移后的真实参考。
React Native 用户：官方推荐的替代方案
changeset 明确给出结论：React Native 场景不再由 react-spring 提供支持，官方推荐使用Reanimated，理由是：
its springs run on the UI thread, unlike react-spring's JS-thread engine.
即 Reanimated 的 spring 动画运行在UI 线程，而 react-spring 的引擎运行在JS 线程，因此在 React Native 上 Reanimated 具备更优的性能基础。这属于该 changeset 中唯一一条带明确论据的替代建议（其官方文档链接见 changeset 原文，仓库内不包含该依赖）。迁移时需将原有@react-spring/native的动画代码逐步改写为 Reanimated 的 API（如useSharedValue、useAnimatedStyle、withSpring等），并注意两者 API 形态不同，无法机械替换。
迁移后的仓库结构参考
移除废弃目标后，本仓库的可发布包组织如下：
- 核心与工具：
@react-spring/core（packages/core/）、@react-spring/animated（packages/animated/）、@react-spring/shared（packages/shared/）、@react-spring/types（packages/types/）、@react-spring/rafz（packages/rafz/） - 渲染目标：
@react-spring/web（targets/web/）、@react-spring/three（targets/three/） - 附加：
@react-spring/parallax（packages/parallax/） - 示例与文档：
demo/与docs/（在 .changeset/config.json 中被ignore，不随@react-spring/*组发布）
快速自检清单
迁移完成后，可通过以下方式快速确认没有残留：
- 全局搜索代码中是否还存在
from 'react-spring'、from '@react-spring/native'、from '@react-spring/konva'、from '@react-spring/zdog'的导入； package.json中不再出现上述四个包名；- 锁文件（
package-lock.json/yarn.lock/pnpm-lock.yaml）重新生成后无相关包残留； npm ls react-spring（或pnpm why react-spring）无输出，或仅剩间接依赖时核实其来源。
总结
本次 changeset 是一次面向下一个主版本（major）的清理型破坏性变更：删除三个早已废弃的渲染目标（native / konva / zdog）及其 React Native Hook 变体，并移除多余的react-springumbrella 包。对绝大多数 Web / Three.js 用户而言，迁移动作收敛为「把 import 来源改成@react-spring/web或@react-spring/three」这一条；React Native 用户则需要切换到 UI 线程驱动的 Reanimated。仓库当前 targets/ 目录只保留 web 与 three 两个目标，与变更声明完全吻合，也印证了 react-spring「核心引擎 + 渲染目标」架构向更精简方向收敛的趋势。
【免费下载链接】react-spring✌️ A spring physics based React animation library项目地址: https://gitcode.com/gh_mirrors/re/react-spring
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
