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.mdfrontmatter 声明--- 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/threeReact 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/coreSpring 物理引擎、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 调度。渲染目标包绑定具体平台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 场景。因此用户通常只需要安装一个目标包即可拿到完整 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: pnpm9.15.9、engines: { node: 24.16.0 }请确保包管理器与 Node 版本满足要求。第二步修改 import 语句Web 项目import { useSpring, animated } from react-spring→import { useSpring, animated } from react-spring/webThree.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 及以上含 19react-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-springs 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/corepackages/core/、react-spring/animatedpackages/animated/、react-spring/sharedpackages/shared/、react-spring/typespackages/types/、react-spring/rafzpackages/rafz/渲染目标react-spring/webtargets/web/、react-spring/threetargets/three/附加react-spring/parallaxpackages/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），仅供参考