前两天在 Android 端接应用内截图功能调研了一圈最后选了 react-native-view-shot。本以为调好几个参数就完事结果从空白截图、FileUriExposedException一路踩到 Android 13 权限闪退前前后后折腾了一整天。这篇就把我在 RN Android 下用 react-native-view-shot 遇到的所有问题、排查思路和最终能跑的方案完整记下来。如果你也在做 RN 截图功能或者正被 content:// 这种 Uri 路径搞晕这篇文章应该能帮你少踩不少坑。这个需求不挑基础刚接触 RN 的新手能避开大部分天坑被新老架构迁移折磨过的老手也能在这里找到一些排查线索。1. react-native-view-shot 到底干了什么1.1 它并不是真的“截屏”很多人第一次用 react-native-view-shot会误以为它是调用系统截屏接口把整个屏幕拍下来。实际上完全不是这么回事。它的核心 APIcaptureRef拿到的是你传入的一个 React View 实例然后原生端通过 UIManager 拿到这个 View 对应的 Android 原生节点再复用 Android 的View.draw(Canvas)方法把视图树里的普通 View 重新绘制到一张 Bitmap 上最后导出成临时文件、base64 或>file:///data/user/0/com.example.app/cache/ReactNative-snapshot-image-xxx.png这个文件随时可能被系统清理所以如果你想把它保存到相册或者分享出去还需要再走一步“拷贝到公共目录”的逻辑。很多新手在这里被file://和content://绕晕其实本质就是 Android 文件共享规则的问题后面第 2 章我会专门展开。1.2 为什么我推荐用 captureRef 而不是 captureScreenreact-native-view-shot 还暴露了一个captureScreen()方法听名字感觉可以直接截整个屏幕省去传 ref 的麻烦。但我实际用下来这个 API 在 Android 上非常不靠谱。它早期实现依赖 MediaProjection 之类的系统能力需要用户授权部分国产 ROM 上还要额外开悬浮窗权限。即便授权成功在某些机型上截出来的也可能是一张黑屏或者只有当前 Activity 的窗口状态栏、导航栏时有时无。我自己的建议是99% 的应用内截图需求都应该用captureRef把你要截的内容老老实实放进一个View里然后对这个 View 截图。这样结果是可控的不受系统窗口影响也不需要额外权限。只有那种要截整个应用界面、还要包含系统 UI 的场景才需要往captureScreen方向考虑但那种场景往往不如直接走原生自定义实现。1.3 新老架构和版本选择这一步就淘汰了很多人React Native 从 0.70 左右开始推新架构到 0.76 后新架构成了默认选项。react-native-view-shot 对这块的适配是有明确版本分界的3.x 只支持旧架构的 bridge NativeModule 注册方式4.x 才完整适配新架构的 TurboModule 和 Codegen。如果你用的 React Native 版本是 0.74 以上且开了新架构但项目里安装的 react-native-view-shot 还是 3.4.0一调用就会报NativeModule: RNCViewShot is null因为原生端根本没有注册这个模块。安装时我建议直接装最新版npm install react-native-view-shot如果你是从旧版本升级上来的最好先卸载再重装避免 Metro 缓存了旧模块npm uninstall react-native-view-shot npm install react-native-view-shotlatestAndroid 端只要用了自动链接一般重新构建一次就行。但如果遇到莫名的 NativeModule 找不到多半不是库的问题而是构建缓存这个在第四章我会讲怎么清理。2. Android 端最容易翻车的四个点2.1 一截图就空白或黑屏这是我在各种技术群里被问得最多的问题。一般来说空白和黑屏要分开看。空白通常是视图引用本身没生效黑屏则往往是碰到了硬件图层的内容。先说空白。RN 在 Android 上有一个非常隐蔽的优化如果某个 View 只用来做布局容器没有任何背景、也没有子 View 需要单独绘制系统可能会把它“合并掉”导致ref拿到的原生节点不存在。截图时就会得到空白图甚至报错No view found for reactTag。解决办法很简单给被截图的 View 加一个collapsable{false}View ref{viewRef} collapsable{false} style{{ flex: 1, backgroundColor: #fff }} {/* 真正要截图的内容 */} /View这个属性告诉 Android这个原生 View 不要被布局优化合并保留它作为独立节点。无数人截图空白其实就是少写了这一行。再说黑屏。如果页面里有视频播放器、高德/百度地图、WebView 这类带独立硬件绘制的组件react-native-view-shot 默认截不到里面的内容。它们内部往往是 SurfaceView 或 TextureView内容不在 Activity 的 View 层级里View.draw(Canvas)只能画出一个空壳。这种问题不是配置参数能解决的只能换思路视频考虑让播放器对外提供帧数据或者用原生端去采集画面。地图让地图库提供静态图快照接口再叠加到你截的图上。WebView尝试先拦截 WebView 的截图或者用 RN 的react-native-webview自带的captureRef属性但兼容性也有限。另外还有一个常见情况页面里有网络图片截图时图片还没加载完截出来就是一个白色的占位块。解决办法是等图片onLoad后再截或者先预加载图片。不要在页面刚跳转过来、任务队列还没执行完时就急着按截图按钮。2.2 FileProvider 与 content:// 路径坑captureRef返回的默认 Uri 是file:///data/user/0/包名/cache/...这样的路径。在 Android 7.0 之后系统禁止应用之间直接通过file://分享文件否则会抛FileUriExposedException。这就是你在很多报错日志里看到content://com.xxx.fileprovider/...的原因——正规的跨应用文件传递必须通过 FileProvider 把一个文件路径转换成带授权信息的 content Uri。你可能会在网上看到类似这样的 Uricontent://你的包名.fileprovider/外部路径/Android/data/你的包名/...它本质上就是 FileProvider 生成的授权地址。如果你只是用 CameraRoll 保存到相册react-native-view-shot 返回的file://临时文件是没问题的CameraRoll 内部会处理拷贝。但如果你要把这个截图直接分享到微信、钉钉或者自己写原生模块转发给其他 App就不能直接传file://路径了。最省事的做法是不要把 FileProvider 的细节暴露到 JS 层。分享功能直接用react-native-share它会自己处理 content Uri 的生成。如果你确实需要自己生成 FileProvider Uri原生端要配置两步第一步在 AndroidManifest.xml 里注册 FileProviderprovider android:nameandroidx.core.content.FileProvider android:authorities${applicationId}.fileprovider android:exportedfalse android:grantUriPermissionstrue meta-data android:nameandroid.support.FILE_PROVIDER_PATHS android:resourcexml/file_paths / /provider第二步在res/xml/file_paths.xml里指定可暴露的目录paths cache-path namecache pathcache/ / external-path nameexternal path. / /paths然后在原生代码里用FileProvider.getUriForFile()转换成 content Uri再传给目标应用。这里面的坑在于如果你在paths.xml里没有包含截图临时文件所在目录转换时会直接抛异常。很多人在这一步被绕晕其实只要记住“file:// 是内部用content:// 是给外部用”就够了。2.3 Android 13 以后读写权限没那么简单如果只是“截图并保存到相册”很多人以为一定要申请存储权限。实际上从 Android 10 开始系统强制分区存储App 通过 MediaStore 往公共相册插入一张图片并不需要WRITE_EXTERNAL_STORAGE权限。到了 Android 13情况又变了如果要读取系统相册里的图片需要申请READ_MEDIA_IMAGES如果只是写入依然可以不用权限。真正容易翻车的地方在于项目里如果还保留着旧版 CameraRoll或者用 react-native-fs 直接把截图写到/storage/emulated/0/xxx在 Android 10 上可能写入不进去或者写进去了在相册里看不到。我的建议是保存相册直接用react-native-camera-roll/camera-roll它内部封装了 MediaStore 的插入逻辑兼容性比手写文件拷贝好很多。如果你还需要读取相册里的图片比如做一个“从相册选择图片后再截图标注”的功能那就要在 Android 13 系统上运行时请求READ_MEDIA_IMAGES并且把 targetSdk 更新到 33 以上。react-native-camera-roll/camera-roll提供了requestReadWritePermission()方法可以在调用前主动检测并申请权限比自己在 JS 层调 PermissionsAndroid 省心。我在真机上遇到过一种情况Android 13 的 Pixel 上不申请任何权限直接调用CameraRoll.save是成功的但同一个包在小米的 Android 13 上会返回 permission denial。这跟厂商对权限的额外控制有关。所以不要抱着侥幸心理权限请求该加还是加。2.4 截图时序动画、键盘和弹窗截图看起来是瞬时操作但 RN 的原生绘制和 JS 任务线程不是完全同步的。我踩过一个很典型的坑页面右下角有个浮动按钮点击它的瞬间有个涟漪动画紧接着马上触发截图截出来的图片上按钮边缘是半透明的、甚至缺一块。原因是截图发生的时候涟漪动画还没有结束View 正处于中间态。解决办法是根据动画时长做一个短延迟。不要依赖一个固定的setTimeout(500)就完事更好的做法是InteractionManager.runAfterInteractions(async () { const uri await captureRef(...); });runAfterInteractions会等当前所有交互任务和部分 JS 任务执行完但它不等原生动画。如果页面确实有动画还是要配合延时。运动中的动画如果只需要静态结果建议先把动画停掉或者把要截的动画元素用一个稳定的快照容器包起来。还有一个很隐蔽的坑键盘弹起时截图。Android 的adjustResize模式会让整个 Activity 重新布局如果你的页面包含 TextInput截图前应该先收起键盘并等键盘真正隐藏后再截。我当时在截图前调用Keyboard.dismiss()然后立刻截图结果截出来的输入框位置偏了。后来监听keyboardDidHide事件等回调后再截才稳定。3. 一套可以直接抄的完整实现3.1 截图并保存到相册的完整代码下面这段代码是我在项目里验证过的方案目标是把一个自定义 View 截图并保存到系统相册。依赖就两个库npm install react-native-view-shot npm install react-native-camera-roll/camera-roll核心代码import React, { useRef, useCallback } from react; import { View, Button, Alert } from react-native; import { captureRef } from react-native-view-shot; import { CameraRoll } from react-native-camera-roll/camera-roll; export default function SnapshotScreen() { const viewRef useRef(null); const handleSnapshot useCallback(async () { if (!viewRef.current) { Alert.alert(提示, 截图区域还没准备好); return; } try { const uri await captureRef(viewRef, { format: png, quality: 1, result: tmpfile, }); const saved await CameraRoll.save(uri, { type: photo }); Alert.alert(成功, 图片已保存到相册); } catch (e) { Alert.alert(失败, 截图保存失败${e.message}); } }, []); return ( View style{{ flex: 1 }} View ref{viewRef} collapsable{false} style{{ flex: 1, backgroundColor: #fff, justifyContent: center, alignItems: center, }} {/* 这里放你真正要截图的内容 */} View style{{ width: 200, height: 100, backgroundColor: #1677ff, borderRadius: 4, }} / /View Button title截图并保存 onPress{handleSnapshot} / /View ); }如果你用的是 React Native 0.72 之前的版本CameraRoll 的 API 可能还是CameraRoll.saveImage()新版改成了save()。升级之后要留意这一点。Android 端权限申请这块建议直接使用 CameraRoll 提供的辅助方法import { CameraRoll } from react-native-camera-roll/camera-roll; const hasPermission await CameraRoll.requestReadWritePermission(); if (!hasPermission) { Alert.alert(提示, 需要相册权限才能保存图片); return; }注意requestReadWritePermission并不是所有版本都有不同版本 API 名可能有差异。用之前去 node_modules 里看一眼类型定义是最稳妥的。3.2 options 参数怎么选才不踩坑react-native-view-shot 的captureRef第二个参数是 options这里面的门道不少。format建议在没有透明背景需求时用jpg体积小、保存快。但如果你截的 View 用了圆角、半透明背景jpg 会把透明区域填成黑色这时候应该用png。一般 UI 分享卡片我推荐 png照片类内容推荐 jpg。quality只在 jpg 时有效取值 0 到 1。大多数场景直接用 0.9 就够了肉眼几乎看不出区别文件体积能小不少。我之前为了省体积调到 0.7结果在人像边缘出现明显马赛克后来就一直用 0.9。result有三个可选值tmpfile、data-uri、base64。我的原则是能选 tmpfile 就选 tmpfile尤其是图片尺寸大时。base64 会把整个图片塞进内存截图长图时很容易 OOM。只有在你要直接把图片通过接口上传且不想管理临时文件的时候才考虑 base64并且要控制图片分辨率。width和height可以指定输出图片的像素尺寸。如果不传默认使用视图的实际尺寸乘上屏幕 density。有的截图在相册里看起来偏小就是因为视图尺寸不大。你可以这样主动设置高分辨率const { width, height } Dimensions.get(window); const uri await captureRef(viewRef, { format: png, quality: 1, result: tmpfile, width: width * 2, height: height * 2, });这样输出的图片会清晰很多适合生成海报。snapshotContentContainer是 ScrollView 场景下的神器。设为true后可以截取整个滚动内容而不仅限于当前可视区域。但它消耗的内存也会明显上升使用时要注意控制内容高度。3.3 长页面截图和内存控制很多人想做“长截图”也就是把整个 ScrollView 内容一次性截成一张长图。react-native-view-shot 提供了snapshotContentContainer确实能截但代价是内存。如果列表里只有几屏内容还好一旦你的 ScrollView 内容超过 3000dp换算成像素就是几千乘几千的 Bitmap内存占用非常恐怖。我实测过一张 4000px 高的截图低端机上内存瞬间飙到 300MB页面直接被杀后台。所以如果产品真正需要长图我的建议是控制输出尺寸尽量把 width 设置成 750 左右而不是原图两倍。不要对动态长列表直接截最好由服务端生成长图卡片。如果非要在端上截可以分段截取多个 View再通过原生端拼接成一张长图但这个复杂度已经超出 react-native-view-shot 的职责了。另外临时文件生成后不会自动清理。如果用户频繁截图缓存目录会越来越大。建议每次截图后对旧文件做一次清理或者用原生端定期清理 cache 目录。4. 问题排查与避坑记录4.1 常见报错速查表下面是我在实际开发中遇到的典型报错以及对应的解决思路。报错信息或现象可能原因解决办法NativeModule: RNCViewShot is null库版本不兼容新架构或者 autolinking 没有生效升级到 4.x清构建缓存重新构建Error: No view found for reactTagref 绑定的 View 不存在或者被布局优化合并给目标 View 加collapsable{false}并确认 ref 已挂载截图是一张纯白图内容还没渲染完成或者网络图片未加载等onLoad和布局完成后再截必要时加短延时截图是黑屏页面包含 SurfaceView/TextureView/WebView这类硬件图层无法通过 draw 截取换方案FileUriExposedException把 file:// 路径直接传给其他 App使用 FileProvider 转 content Uri或交给分享库处理CameraRoll.save拒绝访问Android 13 相册权限不足或厂商限制运行时申请READ_MEDIA_IMAGES用 CameraRoll 的集成权限方法截出来的图片尺寸不对options 没有设置 width/height或视图尺寸为 0检查目标 View 的布局主动传入期望的分辨率这表里最后一行很值得多说一句。如果目标 View 正在做显示动画比如transform: scale(0)初始状态它的测量宽高可能是 0截出来就是空图。这种情况可以先在截图前临时设置一个确定尺寸或者等动画结束。4.2 用 Android Studio 和 adb 定位问题截图这种偏原生的问题只靠 console.log 有时候很难看出头绪。我习惯把 Android Studio 的 Logcat 打开过滤器里同时加ReactNativeJS和RNCViewShot这样 JS 报错和原生模块日志能一起看到。如果captureRef返回了路径但保存相册失败可以用 adb 查看缓存文件是否存在adb shell run-as 你的包名 ls cache/注意run-as仅对 debug 包有效。release 包签名不一样通常无法直接查看。这个命令能帮你快速确认临时文件有没有生成出来。如果截图已经保存到相册但相册里看不到可以检查公共目录adb shell ls -l /storage/emulated/0/Pictures如果文件在但相册不刷新那就不是截图的问题是 MediaScanner 没有扫描。这里顺便提一个调试技巧adb exec-out screencap -p screen.png可以截取整个系统屏幕适合用来对比应用内截图和系统全屏截图之间的区别但它和应用内截图完全不是一回事。4.3 新老架构下的最后一个冷门坑即使你已经装了 4.x 版本的 react-native-view-shot在新架构下还是有可能遇到类找不到、模块为 null 的情况。原因通常不是库本身而是 Codegen 生成的产物没有及时更新。这种问题我有两次是靠清理工程解决的cd android ./gradlew clean npx react-native start --reset-cache如果项目刚升级完 React Native 版本最好把整个 android 下的 build 目录删掉重新构建。很多“玄学问题”实际上都是旧构建残留导致的。另一个冷门坑是新版 React Native 默认新架构但部分老项目的gradle.properties里还写着newArchEnabledfalse。如果你在升级后用了一个只支持旧架构的三方库整个 App 可能直接编译失败。而 react-native-view-shot 4.x 同时兼容新老架构所以它反而是一个很好的“架构迁移试金石”。如果这种纯 JS 包在迁移后能正常跑说明你的原生工程配置基本没问题。5. 截图之后的事保存、分享和产品化5.1 保存到相册后刷新与分享截图保存到相册后偶尔会出现“明明保存了但相册里看不到”的情况。本质上是因为 MediaStore 插入文件后相册应用没有及时刷新。用react-native-camera-roll/camera-roll的save()一般会自动触发 MediaScanner 扫描所以不推荐自己手动把图片文件拷到公共目录再发广播。分享截图则是另一个常见场景。如果你先把图片保存到相册再从相册拿 url 去分享中间会多一层权限和路径的转换。更好的做法是先captureRef拿到临时文件直接把临时文件交给react-native-share让它内部处理 FileProvider。这样分享链路短、权限问题少。如果你需要分享的同时保存相册那就分别调用两个库不要在 JS 层共享同一个 file:// 路径。5.2 截图功能还能怎么玩react-native-view-shot 不只是用来“截图给用户看”。我用它做过分享卡片生成器把一段业务数据渲染成一张带背景图和用户信息的 View然后整体截图保存效果比用 canvas 手绘简单得多。朋友圈裂变海报、订单凭证、成绩单分享都可以走这个思路。还有个热门方向是“截图翻译”。很多截图工具会把截图区域截下来然后送 OCR 识别并翻译。放到 App 里你可以在应用内截取当前页面拿到图片后跳到一个编辑/识别界面做标注、高亮、OCR形成完整闭环。react-native-view-shot 作为第一步的采集工具足够轻量不会给主包增加太多体积。5.3 我最终确定的实践方案截图这种事看起来只是把一个 View 变成图片背后却牵扯到 Android 的绘制机制、文件共享规则和权限模型。react-native-view-shot 能帮你解决 80% 的场景但剩下 20% 的视频、地图、长图场景最好在设计需求时就规避掉或者直接交给原生端定制。如果你现在正要启动一个 RN 截图需求我建议先问清楚三件事截图范围是局部还是全屏要不要包含视频或 WebView产物是保存到相册还是分享到别的 App这三个问题确认完方案基本就定了。最后再多说一句上线前一定多拿几台不同 Android 版本的机器测一测尤其是 Android 13 和 14 的全面屏手机截图这种功能最容易在系统差异上翻车。希望我这些踩坑记录能帮你省下一个下午的时间。