1. 一次依赖引发的App启动闪退我先把我踩过的坑摆出来做React Native开发的朋友应该都有过这种经历项目跑得好好的为了加一个小功能装了个npm包结果重新build之后整个App直接白屏或者启动就崩。我去年做一个跨平台应用的时候就遇到过一次当时只是想在详情页加一个图片轮播装了个react-native-image-swiper结果iOS端编译过了Android端死活装不上最后发现是它依赖的旧版react-native-view-shot和我项目里另一个库的版本产生了冲突。类似的场景在RN社区里几乎每天都在发生这就是依赖管理没做好的典型后果。这篇内容不打算写那种从零搭建RN环境的新手教程而是聚焦在一个更实在的问题上一个正经要上架的RN app到底需要哪些依赖为什么需要它们以及当依赖之间打起来的时候怎么收场。我基于自己维护过的一个包含登录、支付、地图、推送、分享、IM等多模块的RN项目把最终沉淀下来的依赖清单和踩坑记录整理了一遍。适合正在搭建RN项目、或者项目已经跑起来但依赖管理比较混乱的开发者参考看完之后你至少能回答自己两个问题这个包为什么要在它为什么不能随便升版本。需要先说明一点本文后面提到的依赖版本号是基于React Native 0.72.x这个版本线来展开的。RN的版本迁移比较特殊它不像普通npm包那样独立升级新的RN版本往往会带动一批核心依赖的连带变更所以如果你的项目还在0.6x或者已经升到0.7x之后的版本具体版本号要按实际情况调整但管理和排查的思路是通用的。2. 把依赖分层来看dependencies、devDependencies和peerDependencies各管什么很多RN开发者在项目初期会把所有能装的包全部塞进dependencies我也这么干过直到后来发现node_modules里有六十多个包根本不知道是干什么用的才意识到依赖分层这件事从一开始就要做清楚。package.json里三个字段的分工其实非常明确我按自己项目的实际用法来拆解一下。dependencies里放的是App运行期真正需要的库。比如react、react-native、react-navigation、axios这些它们在App打包上线之后依然要被加载执行。这个字段里的每一个包都应该能回答为什么App少了它就跑不了这个问题。如果某个包只是开发阶段用一下打包后完全不影响运行那它就不应该待在这里。devDependencies放的是只在开发流程中使用的工具链。比如babel相关的配置、eslint、prettier、以及typescript的类型声明包。以TypeScript为例typescript本身和types/*系列包它们的作用只是在编译阶段帮你做类型检查编译完成后输出的JS代码并不依赖它们。还有一个典型的例子是react-native-svg的Mock测试框架jest里需要它来模拟SVG渲染但运行时完全用不到。peerDependencies在RN项目里容易被忽略但它恰恰是很多版本冲突的根源。它的意思是我这个包正常工作需要宿主环境提供一个特定版本的依赖。比如react-native-gesture-handler就要求项目里必须装react-native 0.60.0react-navigation则要求react-native-screens存在。如果你的项目满足不了这些peer依赖npm在安装时会报冲突yarn在旧版本时可能只给个警告就装上了结果运行时才炸。这里有一个我在实际项目中吃过亏的点yarn特有的隐式提升机制。yarn会把所有包平铺到node_modules根目录而不是像老版npm那样嵌套安装这本身是为了解决依赖地狱问题但也带来了新的混乱比如一个包本不该被你的代码直接引用却因为提升到了根目录你的代码在import的时候也能引到它。这种幽灵依赖在CI环境里最容易出问题——本地能跑一到干净环境就报module not found。所以我现在维护项目的一个习惯是每个用到的包都在package.json里显式声明为直接依赖绝不依赖某个传递依赖碰巧被提升到这个巧合上。另外还可以用一个名为depcheck的工具定期扫描它能列出哪些依赖声明了但没用过、哪些用到了却忘了声明。3. 从package.json到构建链路RN依赖管理的三大层关系单纯弄明白package.json里放什么还不够因为RN项目和纯前端项目的依赖管理有一个本质区别它跨越了JavaScript、Android、iOS三套生态。一个依赖从你执行npm install到最终跑在用户手机上实际上要经过三层的校验和传递。第一层是JavaScript依赖层。执行npm install或yarn时npm会解析package.json和lockfile把JS包安装到node_modules。这一层主要解决JS代码的依赖关系但恰恰是这一层的问题最隐蔽因为很多RN核心库的JS部分只是个壳它们真正的功能要调到底层原生代码。第二层是Android原生依赖层。RN的Android项目用Gradle作为构建工具Gradle会读取android/build.gradle、android/app/build.gradle以及各个RN库自带的build.gradle文件。当RN库从npm安装后在Gradle构建阶段RN的Gradle插件会通过自动链接autolinking机制找到node_modules里的原生模块并把它们以Gradle依赖的形式引入。这意味着同一个依赖你在npm里装的是JS包在Gradle里装的是AAR或JAR原生包两者的版本可能并不同步。第三层是iOS原生依赖层。iOS端用CocoaPods管理原生依赖执行pod install时CocoaPods读取Podfile和Podfile.lock从node_modules里对应的React Native库中寻找podspec文件将原生代码作为Pods项目引入。CocoaPods的三个核心配置文件各司其职Podfile声明依赖Podfile.lock锁定版本Manifest.lock则用于校验本次安装的pod版本是否和锁定的版本一致。这三层的关系可以用一句话概括JS包版本由package.json管Android原生版本由Gradle管iOS原生版本由CocoaPods管而它们的源头都是node_modules里的同一个包。这也就意味着当你在package.json里把某个依赖从1.x升到2.x时它可能同时牵动了Gradle和Pods两边的原生版本变更任何一边没有正确更新都会导致构建异常。实际开发中最容易出现的典型问题场景是你手动修改了package.json里的某个包的版本但忘了重新执行pod install或Gradle同步。结果就是JS侧已经是新版的API了原生侧还在用旧版的方法运行时就会报Native module cannot be null之类的错误。所以每次改完package.json标准的后续动作应该是npm install或yarn之后Android端同步一下GradleiOS端执行pod install三步缺一不可。4. 三大件之外的高频实用依赖按业务模块逐项盘点导航、网络、状态管理是RN项目的基础三件套但在真实业务里App的功能远不止这些。我把一个相对完整的业务型RN app拆到模块维度逐个模块列出我实际使用过、确认稳定可靠的依赖。登录与安全模块react-native-keychain是处理敏感信息存储的可靠选择它把Token存到iOS的Keychain或Android的EncryptedSharedPreferences比AsyncStorage安全性高得多。react-native-biometrics可以接入指纹和人脸识别适合金融类App登录验证。这里有个关键点不要在JS层直接存储明文密码即使你用AsyncStorage也不行它是明文存储Root或越狱设备上很容易被读走。地图模块react-native-maps是目前最主流的地图封装同时支持Google Map和Apple Map。如果你需要高度定制地图样式或离线地图react-native-mapbox-gl是另一个选择但它的配置复杂度高不少对依赖的原生SDK版本也比较挑剔。Huawei Map Kit在国内的App里也很常见华为设备上表现更稳定。支付模块如果App要上架国内安卓应用商店H5支付和原生支付的接入方式受审核政策影响较大单纯依赖webview内嵌基本走不通。这块通常需要自己写原生桥接或使用各厂商的官方SDK包React Native社区没有一套能通吃各渠道的解决方案。我的建议是支付模块尽量用原生实现通过Native Module暴露给RN调用一方面安全校验好做另一方面各渠道SDK的坑也少一些。推送模块国内推送绕不开厂商通道react-native-push-notification是经典的本地通知方案但它不支持厂商通道。目前国内做全厂商推送集成用得比较多的是极光、个推或Umeng提供的RN插件它们的共同特点是体积大、原生依赖重安装后往往还需要在AndroidManifest里配置一堆推送服务和接收器。分享模块react-native-share基本是唯一选择它封装了系统分享面板支持文本、图片、URL和文件iOS端还能分享到Story。这个库在Android端有时候会出分享面板弹不出来的问题通常和App调用的Activity类型有关需要配合taskAffinity设置去解决。IM模块如果只是做单聊、群聊react-native-gifted-chat是UI层最省事的方案但底层通信还是得接入专业的IM SDK国内常用融云、环信它们都有官方RN插件。这里踩过的一个坑是IM SDK往往自带了okhttp或protobuf这类基础库如果你项目里其他网络库也引入了这些库Gradle去重往往就卡在这里。调试辅助模块react-native-device-info是获取设备信息的万能工具UDID、系统版本、屏幕尺寸、电量这些它都能拿到很多第三方SDK初始化时都要先调用它拿设备参数。react-native-vector-icons是图标库的核心依赖注意它需要在Android和iOS两端配置字体文件并不是装上就能显示的。视频与图片模块react-native-image-picker负责从相册选图或拍照react-native-image-crop-picker在裁剪和压缩上做得更好但体积更大。视频播放用react-native-video这个库在Android端对ExoPlayer的版本要求比较严格如果App里已经存在其他ExoPlayer版本需要用Gradle的resolutionStrategy统一版本。上面这些可以算是业务型RN App的常规依赖底盘当然并不是每个项目都要全上而是要根据业务形态做取舍。比如纯工具类App完全不需要IM和支付但导航和网络几乎任何项目都躲不掉。整理这份清单最主要的价值在于当你需要某个能力的时候不用再去npm上盲目搜索避免装到那些维护不活跃或者和RN新版本不适配的库。5. 版本锁定的工程化实践lockfile、bump策略和依赖更新节奏在我接触过的不少RN项目里package.json里写的是^1.2.3这种带插入符的版本范围lockfile也被丢进.gitignore里。这种做法在个人项目里也许没大问题但放到团队协作或者生产环境里几乎一定会碰到我这边好好的你那边构建就崩的问题。因为^符号的意思是允许安装1.x.x这个范围内的最新版本如果某个依赖发布了1.3.0而它内部引入了breaking change不同人不同时间执行install得到的结果就是不同的。所以在RN项目里第一个工程化原则就是lockfile必须入库。具体来说使用npm就用package-lock.json使用yarn就用yarn.lock。这个文件锁定了每个依赖的精确版本和依赖树结构保证团队所有成员、CI环境和本地环境的依赖一致。如果有iOS原生依赖Podfile.lock同样要入库它记录了CocoaPods各pod的精确版本防止不同成员执行pod install后得到不同的原生配置。Android端的Gradle要锁定wrapper版本gradle-wrapper.properties里的distributionUrl不要随意修改Gradle版本变了整个构建链路的差异可能非常大。第二个原则是明确依赖升级的节奏。我观察下来很多RN项目的依赖版本冲突往往不是因为升级不够积极而是因为升级太随意。今天看到某个库更新了就直接改package.json升上去结果它引入的某个底层库和其他包依赖的版本发生冲突排查起来极其痛苦。建议的做法是给依赖分成两类节奏随RN版本走的核心依赖react、react-native、以及RN官方推荐的配套库比如react-native-community下的包这类依赖紧跟着RN版本走。RN本身发版时会明确说明它支持哪些版本的核心配套库直接按官方说明对齐即可。独立迭代的业务依赖导航、网络、UI组件等这类依赖不受RN版本强绑定可以根据功能需要独立升级。但升级前应该看它的changelog尤其关注peerDependencies有没有变化。比如从React Navigation 5升到6它的peerDependencies就从react-native-gesture-handler扩展到了必须同时装react-native-screens如果漏装了Android端很容易出现导航页面黑屏。第三个原则是不要试图手动维护传递依赖的版本。遇到某个依赖的传递依赖有bug时很多人的第一反应是直接在package.json里把这个传递依赖加进来强制指定版本。这在npm和yarn里确实有效但也会埋下隐患你指定的版本和真正的宿主可能不兼容。举个例子如果react-native-camera内部依赖了一个旧版本的react-native-vector-icons而你在package.json里强制写了新版的vector-icons表面看构建过了但实际运行时可能会因为原生API签名不一致而崩溃。遇到这种情况正确的做法是先看这个依赖有没有发布相应更新或者考虑用patch-package对源码做小幅修复而不是简单粗暴地覆盖版本。6. 依赖安全的底线npm audit与供应链三件套以及锁定私有源依赖多到一定程度安全检查就成了不能跳过的一步。我见过有的团队在开发机上用npm audit发现一堆高危漏洞也无动于衷理由往往是App里面用不到这个功能。这个想法很危险——漏洞利用往往不需要你主动调用某个函数攻击者只要通过你依赖链里的某个漏洞点就能注入代码。依赖安全的底线操作可以归结为三步第一步构建前拦截高危漏洞。在package.json的scripts里加上audit检查每次安装依赖后执行{ scripts: { audit: npm audit --audit-levelhigh } }在CI流程中把npm audit作为构建前置步骤只要存在high及以上等级的漏洞就中断构建从源头阻止高危依赖进入产物。npm audit的返回码逻辑这里说明一下0代表没有漏洞1代表有漏洞但被audit-level过滤忽略了非0返回值在CI里就意味着失败所以实际使用时要根据CI的失败策略调整。第二步用锁文件保障供应链一致。前面已经说过lockfile入库这里再强调一次在CI环境里执行依赖安装时使用npm ci而不是npm install。npm ci会严格按照package-lock.json的锁定版本安装不会做任何版本浮动计算同时速度比npm install更快更适合自动化流水线。第三步规范化私有源和镜像源的管理。团队内部建议统一维护.npmrc文件锁定registry地址。这里有一个容易被忽视的问题不同成员的.npmrc可能有不同的registry配置有的人走了私有代理有的人走了公共源即使lockfile一致安装出来的结果也可能有细微差异。统一.npmrc并入库可以规避这类环境漂移问题。另外如果有条件的话建议定期用一个低权限账号在干净环境里执行npm ci来验证项目能否从零构建。这一步能暴露两个问题一是lockfile是否完整二是是否有依赖在私有源里存在但不在lockfile中。本地node_modules还在的时候npm不会校验这些换个环境就露馅。7. 版本冲突的完整排查链路从报错定位根因的实际操作依赖冲突是RN开发里绕不开的坎这里我花一个完整章节专门讲排查链路。因为直接告诉你哪个包和哪个包冲突没有意义每个项目的组合不一样真正值钱的是当报错来临时你如何一步步缩小范围找到肇事包。以最常见的Android构建报错为例这类能在网上搜到大量类似经历但报错信息很长很多人看到第一行就懵了Could not determine the dependencies of task :app:compileDebugJavaWithJavac. Could not resolve all task dependencies for configuration :app:debugCompileClasspath. Could not resolve com.facebook.react:react-native:0.72.5.这是典型的Gradle层面找不到依赖的报错。排查时不要急着去看react-native版本的问题React Native的Android构建会自动把react-native的版本和构建工具关联起来这里更可能是某个第三方库在你的build.gradle里引用了一个不存在的传递依赖。我的排查顺序是这样的第一步看Gradle的依赖报告。在android目录下执行./gradlew :app:dependencies --configuration debugCompileClasspath这个命令会把当前app模块的完整依赖树打印出来包括每个库的依赖来源和版本。执行后搜索报错里提到的那个坐标比如com.facebook.react:react-native看看它在哪条依赖链上被引用。如果发现这个坐标来自某个第三方库比如react-native-nfc-manager那问题基本就锁定在这个库的版本上了。第二步检查是版本冲突还是版本不存在。如果Gradle报告显示有两个不同版本被同一模块依赖比如某个库依赖react-native 0.71.0而你项目是0.72.5Gradle默认会选较高版本但两种版本并存时可能出现API签名不一致的诡异报错。正确的做法是用Gradle的resolutionStrategy强制统一版本configurations.all { resolutionStrategy { force com.facebook.react:react-native:0.72.5 } }如果是版本不存在则需要在Gradle仓库配置里加上Maven Central的地址repositories { mavenCentral() }很多第三方库发布的AAR只传到Maven Central而RN项目默认仓库顺序是优先Google和JCenter如果某个小程序内部依赖没有被正确解析就会报出Could not resolve错误。第三步处理CocoaPods版本的同类冲突。iOS端冲突的表现更像之前提到的链路pod install时CocoaPods显示某个pod的版本不满足依赖要求或者构建时找不到对应符号。排查时先看Podfile.lock确认一下实际安装的版本是否和podspec声明的一致确认无误后再看是否出现了重复定义。CocoaPods的重复定义会在Podfile里体现为多个target引用了同一个pod如果出现这种情况需要检查node_modules里是不是存在同一个库的不同版本副本。第四步确认是否是新安装依赖导致的回归。如果之前的依赖树是正常的只是最近新增了某个依赖后才出现冲突可以用git回溯package.json的历史记录找到diff点然后定向检查新增依赖的peerDependencies和transfer dependencies。这个是成本最低的定位方式我几乎每次排查都是从这一步开始的。最后补充一个非常实用的命令遇到疑似版本冲突时可以快速查看某个具体依赖的完整逆向依赖npm ls react-native它的输出会显示整个依赖树里react-native被哪些包引用、引用版本是什么。如果出现UNMET PEER DEPENDENCY的标记缺失的peer依赖也就一目了然了。如果输出里多个版本并列展示冲突的准确位置就在那里。8. 我最终沉淀下来的推荐依赖清单一个完整业务型RN app的package.json参考前面讲了不少理论和排查方法最后给一份可以直接参考的依赖清单。这份清单来自我维护的一个包含登录、首页、消息、个人中心、地图、推送、分享等核心模块的RN项目版本基于RN 0.72.xAndroid compileSdk 33iOS Deployment Target 12.0。你完全可以把它当作搭建业务的起点再根据实际场景增删。基础框架依赖{ react: 18.2.0, react-native: 0.72.5, react-native-screens: 3.24.0, react-native-safe-area-context: 4.7.1 }react-native-screens和react-native-safe-area-context是很多导航库和UI库的隐性硬依赖就算你没有直接import它们它们也可能作为peer依赖被间接要求。建议从一开始就装上避免后面被某个库的peerDependencies倒逼。导航与页面结构{ react-navigation/native: ^6.1.9, react-navigation/native-stack: ^6.9.13, react-navigation/bottom-tabs: ^6.5.8, react-native-gesture-handler: ~2.12.0, react-native-reanimated: ~3.3.0 }gesture-handler和reanimated从React Navigation 6开始几乎是标配而且reanimated要求babel插件配合安装后需要在babel.config.js里加上react-native-reanimated/plugin漏掉的话运行时会直接报错。状态管理与网络层{ react-redux: ^8.1.2, reduxjs/toolkit: ^1.9.5, axios: ^1.5.0 }Redux Toolkit的好处是内置了immutable更新逻辑和中间件不用再手动处理action type和reducer的样板代码。axios用于封装统一请求层可以配合axios-retry做网络自动重试。这里有一点要注意axios的拦截器里不要直接处理业务错误码应该在独立的redux slice里做状态更新否则请求层和业务逻辑会耦合得很紧。存储与本地数据{ react-native-async-storage/async-storage: 1.19.0, react-native-keychain: ^8.1.1 }AsyncStorage负责普通的缓存数据比如用户偏好和接口缓存keychain负责敏感数据。这两个边界要划清楚不要图方便把token也放在AsyncStorage里。UI与交互增强{ react-native-vector-icons: ^10.0.0, react-native-linear-gradient: ^2.6.2, react-native-image-picker: ^5.7.0, react-native-image-crop-picker: ^0.40.0, react-native-modal: ^13.0.1 }如果是新项目我建议直接考虑react-native-svg配合自定义图标方案而不是vector-icons因为vector-icons在Android上要做gradle配置字体文件如果更新不及时容易出现显示问号的问题。原生能力与平台桥接{ react-native-community/push-notification-ios: ^1.11.0, react-native-device-info: ^10.8.0, react-native-share: ^9.4.1 }这些库的版本一定要和当前RN版本匹配推荐优先选择React Native社区维护的react-native-community系列更新频率和文档质量都更有保障。第三方个人维护的库则需要在版本升级时格外谨慎。开发依赖{ types/react: ^18.2.21, types/react-native: ^0.72.2, babel/core: ^7.22.17, babel/runtime: ^7.22.15, eslint: ^8.49.0, prettier: ^3.0.3, typescript: ^5.2.2, jest: ^29.6.4, testing-library/react-native: ^12.2.0 }devDependencies这部分在团队开发时很容易被忽略但恰恰是它们保证了代码风格统一、测试覆盖和类型检查。TypeScript项目一定要把react-native的类型声明和运行时版本对齐版本差太多会出现大量红色波浪线但编译能过的奇怪情况。关于这份清单最后想说一点不要直接照搬。版本数字在一段时间后就过时了真正有用的是理解每个依赖存在的理由以及它们之间的协作关系。你在选依赖时如果能回答这个包解决了什么问题、它依赖什么、它升级了会不会影响我的其他依赖这三个问题就已经比绝大多数RN开发者做得更稳了。9. 最后的经验依赖是RN项目的隐形架构我见过不少RN团队代码写得挺规范但依赖管理一团糟package.json里堆满了不知道干什么的包版本全部带^lockfile不入库升级全看心情。这样的项目往往在某个风和日丽的下午突然就构建失败了然后整个团队围着终端排查一整天。依赖这个东西本质上是项目的隐形架构。它的影响力不亚于代码本身的组织方式而且更难被review。一个依赖被移除时可能连带删除了另外两个包依赖的原生配置一个依赖被升级时可能悄悄改变了整个依赖树的结构。我现在的习惯是把依赖变更当成代码变更一样对待每次增删依赖都要走PR流程注明变更原因每季度做一次依赖体检检查依赖数量和最终产物大小发版前在干净环境里从零构建一次确保不是我机器上才能跑。React Native生态的特点决定了依赖管理没有一劳永逸的配方但有了分层意识、锁定机制和排查方法你就能把依赖引发的突发状况从灾难现场变成常规运维。希望这篇内容能帮你少踩几个坑把更多时间花在实际业务开发上。