企业官网建设流程全解析

为什么 Galeria v3 强制要求新架构？Fabric + Expo SDK 54 升级完整指南

【免费下载链接】galeriaThe React (Native) Image Viewer. 📷项目地址: https://gitcode.com/gh_mirrors/ga/galeria

Galeria 是一款 React Native 图片查看器组件，提供共享元素过渡、双指缩放、下滑关闭等原生级体验，并且支持任意图片组件（BYOIC™）。从 v3.0 开始，Galeria 强制要求启用 React Native 新架构（Fabric），这意味着你必须升级至Expo SDK 54+或React Native 0.79+。本指南将讲清楚背后的原因，并手把手带你完成 Fabric 与 Expo SDK 54 的升级。

一、先搞懂：什么是 Fabric 新架构？

React Native 新架构由Fabric（新渲染器）和TurboModules（新模块系统）组成，核心变化是：

对于像 Galeria 这样的图片查看器来说，新架构带来的是一个关键能力：JS 层可以直接持有并操作原生视图实例，从而实现像素级对齐的共享元素过渡动画。

二、为什么 v3 不再兼容旧架构？

看完源码你会发现，Galeria v3 从根上就建立在 Fabric 之上，无法"向下兼容"：

1️⃣ 深度依赖 Expo 新模块 API

Galeria 的原生视图直接继承自ExpoView（iOS）和 Expo Kotlin 模块体系（Android），见 ios/GaleriaView.swift 与 expo-module.config.json。这套 API 本身就只在新架构下工作，旧架构根本没有对应的运行时。

2️⃣ 视图注册机制实现共享元素过渡

iOS 端通过 ios/GaleriaViewRegistry.swift 把列表中的原生图片视图注册进全局注册表，点开大图时由 ios/Transition/ 的过渡引擎精确匹配源视图与新视图，做无缝缩放动画。这种"跨层级直接引用原生 View"的玩法，是旧架构消息桥模式做不到的。

3️⃣ 面向 Fabric 的视图回收做了优化

Fabric 会回收复用原生视图（View Recycling）。你在 ios/GaleriaView.swift 的setupImageView()中能看到专门的状态清理逻辑——移除旧手势、注销注册表，防止回收后的视图串状态。这些处理只对 Fabric 有意义。

4️⃣ 面向未来的性能红利

新架构的异步渲染与并行加载，让图库这类"大量图片 + 复杂手势"的场景滚动更流畅、启动更快。与其同时维护两套架构，不如直接拥抱它。

三、升级前对照：最低版本要求清单

在动手前，先用这张表检查你的项目：

💡 注意：Expo SDK 56 的ExpoModulesCore同样要求 iOS 16.4+，所以提高部署目标是迟早的事，不如升级时一次到位。

四、Expo 项目完整升级步骤（5 分钟完成）

步骤 1：升级 Expo SDK 到 54+

以 Yarn 为例，将expo、react-native及相关 expo 包升至 54 系列，并运行官方升级工具自动处理配置变更（工具会提示是否开启新架构相关项，选Yes）。

步骤 2：安装 Galeria

yarn add @nandorojo/galeria

步骤 3：设置 iOS 最低部署目标为 16.4

Expo 项目使用expo-build-properties插件，在 example/app.json 的plugins中配置：

[ "expo-build-properties", { "ios": { "deploymentTarget": "16.4" }, "android": { "minSdkVersion": 24 } } ]

裸 React Native 项目则直接修改ios/Podfile中的platform :ios为 16.4。

步骤 4：重新生成原生工程并构建

Galeria 含 Swift（ios/ImageViewer.swift/）与 Kotlin（android/src/main/java/nandorojo/modules/galeria/）原生代码，安装后必须重编原生层：

npx expo prebuild --clean npx expo run:ios # 或 npx expo run:android

步骤 5：安装开发客户端运行

由于是原生模块，Expo Go 无法运行 Galeria。参考示例工程的启动方式（example/package.json）：

npx expo start --dev-client

至此，一个支持新架构的 Galeria 环境就搭建完成了。打开示例工程的 example/app/index.tsx，即可看到点击缩略图后共享元素放大的完整效果。

五、常见踩坑点

• 忘了重新 prebuild：修改原生依赖后不重新生成工程，会直接链接失败。
• iOS 部署目标低于 16.4：过渡动画相关 API 不可用，务必按步骤 3 调整。
• 用 Expo Go 测试：必然报"找不到原生模块"，请切换到 Dev Client。
• Next.js / Web 用户：Galeria 在 Web 端是纯 React 实现（基于 Framer Motion），无需 Fabric，把@nandorojo/galeria加入transpilePackages即可。

六、总结

Galeria v3 强制 Fabric 并不是"制造门槛"，而是因为共享元素过渡、原生视图直引用、视图回收这三大核心能力都构建在新架构之上。好消息是：Expo SDK 54 对老项目而言是一次顺路的升级，跟着本文 5 个步骤走，几分钟即可完成迁移，换取的则是像素级流畅的原生图片查看体验。🚀

【免费下载链接】galeriaThe React (Native) Image Viewer. 📷项目地址: https://gitcode.com/gh_mirrors/ga/galeria