Galeria 常见问题排查清单：z-index 错乱、Expo Go 报错、iOS 16.4 等 10 大坑点一次讲透

Galeria 常见问题排查清单z-index 错乱、Expo Go 报错、iOS 16.4 等 10 大坑点一次讲透【免费下载链接】galeriaThe React (Native) Image Viewer. 项目地址: https://gitcode.com/gh_mirrors/ga/galeriaGalerianandorojo/galeria是一款面向 React 和 React Native 的图片查看器组件库支持共享元素转场、双指缩放、双击放大、下拉关闭和多图浏览最大特点是兼容任意图片组件BYOIC。本文整理出新手使用 Galeria 时最容易踩中的 10 个坑逐一给出排查思路和解决办法帮你快速定位问题。坑点速览#问题现象典型原因1Web 端查看器被列表图片遮挡Masonry 列表破坏 z-index 层级2Expo Go 中查看器无法打开原生模块不被 Expo Go 支持3iOS 低版本机型闪退/白屏部署目标低于 iOS 16.44升级后模块加载失败未启用 New Architecture5Next.js 下报语法错误未加入 transpilePackages6查看器打开的是空白图urls 与实际图片不匹配7控制台报宽高比警告Galeria.Image 与子图尺寸不一致8Web 端无法滑动浏览多图Web 版为简化实现9iOS 背景模糊/页码点想隐藏未设置 iOS 专属属性10点击图片无任何反应组件嵌套结构错误坑 1Web 端 z-index 错乱查看器被图片压住这是官方演示视频里就专门提到过的现象在 Web 端配合 FlashList 的 Masonry 布局使用时全屏查看器看起来像被压在列表下面。原因是 FlashList 的 Masonry 模式会给每个单元格额外包裹一层视图打破了正常的 z-index 堆叠顺序属于列表组件带来的副作用并非 Galeria 本身的核心缺陷。官方示例里给出的解法是自定义CellRendererComponent按索引给每个单元格动态设置zIndex: 100 - index让靠前的图片层级更高。参考示例写法example/app/masonry.tsx。坑 2Expo Go 里报错打不开必须用 dev clientGaleria 在 iOS 和 Android 上依赖原生库iOS 是 SwiftAndroid 是 Kotlin见 ios/ 和 android/src/main/java/nandorojo/modules/galeria/而 Expo Go 无法加载第三方原生模块。典型表现是查看器点击无反应或提示找不到原生模块Native module cannot be null。解决办法只有切换成 dev client 并重新编译原生代码npx expo prebuild npx expo run:ios # 或 npx expo run:android如果本地调试方便也可以直接git clone https://gitcode.com/gh_mirrors/ga/galeria后进入example目录体验官方示例应用。坑 3iOS 16.4 部署目标要求查看 iOS 端 podspec ios/Galeria.podspec 可以看到s.platform :ios, 16.4即 Galeria 硬性要求 iOS 16.4。如果你的 App 部署目标更低在旧机型上会出现类找不到导致的崩溃。裸 RN 项目在ios/Podfile中把platform :ios调到 16.4 以上Expo 项目通过expo-build-properties插件配置参考示例 example/app.json 中的写法deploymentTarget字段坑 4必须启用 New ArchitectureFabricGaleria v3.0 要求 New Architecture对应 Expo SDK 54 或 React Native 0.79。如果你的项目还是旧架构会出现原生模块注册失败、查看器无法弹出的问题。原生模块注册信息定义在 expo-module.config.jsoniOS 注册GaleriaModuleAndroid 注册nandorojo.modules.galeria.GaleriaModule。升级架构后再重新构建即可。坑 5Next.js 项目忘记配置 transpilePackages在 Next.js或 Solito中使用 Galeria 时需要在next.config.js的transpilePackages中加入nandorojo/galeria否则会出现Unexpected token之类的语法编译报错。module.exports { transpilePackages: [nandorojo/galeria], }坑 6urls 与真实图片对不上打开是空白Galeria urls{...}传入的数组是查看器展示什么的唯一依据Galeria.Image里的子节点只负责触发点击。新手常见错误是urls里放了占位符或本地图片用 import 引入后urls仍写成了 URL 字符串导致查看器里出现空白图。正确做法urls中的每一项都要与对应index的图片一一对应本地图片直接import后传入数组即可参考 README.md 中 Multiple Images 一节的写法。坑 7开发模式下宽高比警告导致动画怪异在 Web 开发模式下如果Galeria.Image的宽高和子图片实际宽高不一致控制台会打印[galeria] Galeria.Image does not have the same aspect ratio as its child警告展开动画会显得跳。修复方式很简单给Galeria.Image传style让它的height和width与图片保持一致警告逻辑见 src/GaleriaView.tsx。坑 8Web 端不支持多图滑动需要明确预期Web 版是基于 Framer Motion 的简化实现同一时间只支持一张图片的查看交互多图片左右滑动是 iOS/Android 原生端的能力。如果你的业务在 Web 端也依赖滑动切换需要在业务层自行实现切换逻辑。坑 9iOS 专属属性——隐藏模糊遮罩与页码指示器iOS 查看器默认会在背景加模糊遮罩、多图时底部显示页码圆点部分场景需要关掉。这两个属性是iOS 专属直接写在Galeria.Image上hideBlurOverlay隐藏背景模糊遮罩hidePageIndicators隐藏页码指示点完整属性清单见 src/Galeria.types.ts还包括onIndexChange获取当前浏览索引、onDismiss、onLongPress等回调方便同步 UI 状态。坑 10点击图片没反应先检查嵌套结构新手最频繁的低级错误Galeria.Image没有放在Galeria内部或多图时index与urls数组下标错位。正确结构必须是父子嵌套Galeria urls{urls} {urls.map((url, i) ( Galeria.Image key{i} index{i} Image source{{ uri: url }} / /Galeria.Image ))} /Galeria另外注意 Web 端查看器通过 Portal 挂载到 bodyzIndex: 100如果页面里有层级更高的固定弹层也可能盖住查看器可参考 src/GaleriaView.tsx 中PopupModal的实现理解层级关系。总结排查顺序检查项1是否在 Expo Go 运行→ 换 dev client 重建2iOS 部署目标 ≥ 16.4Expo ≥ SDK 54 / RN ≥ 0.793urls与图片是否一一对应index是否正确4Web 端是否 Masonry 场景的 z-index 问题是否 Next.js 忘了转译按这份清单从上到下排查Galeria 绝大多数玄学问题都能快速收敛。它本质上是个 API 很干净的库问题大多出在运行环境Expo Go、旧架构、iOS 版本和 Web 端层级这两类外部因素上。【免费下载链接】galeriaThe React (Native) Image Viewer. 项目地址: https://gitcode.com/gh_mirrors/ga/galeria创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考