React Native 开发指南

运行和调试 React Native 应用

本文由 AI 协助更新

本文讲述如何运行和调试 React Native 应用。

下文中的运行与调试步骤均需先完成「安装 NPM 包依赖」一节。

安装 NPM 包依赖

克隆代码

git clone git@github.com:listenzz/MyApp.git

安装 npm 包依赖

yarn install

每次更新代码后，如果 NPM 依赖发生变更，需要再次执行 yarn install 更新本地依赖

npm 包安装完成后，通过以下命令启动 Metro（Package Server）：

npm start

运行 Android 项目

启用 USB 调试

真机默认只能安装来自应用商店的 App。开发时需先开启 USB 调试：进入 设置 → 关于手机 → 软件信息，连续点击 版本号 七次以启用「开发者选项」；回到 设置 → 开发者选项，开启 USB 调试。

连接设备并检查

用 USB 线连接手机与电脑，在终端执行：

adb devices

右侧显示 device 表示已连接；若为 unauthorized，请在手机上允许 USB 调试，必要时再执行一次 adb reverse tcp:8081 tcp:8081。同一时间建议只连接一台设备。

连接 Metro

连接开发机上的 Metro（npm start）有两种方式：

  • 方式一：adb reverse（推荐）
    设备需 Android 5.0 及以上、已开启 USB 调试并连上电脑。执行：
adb -s <设备名> reverse tcp:8081 tcp:8081

设备名可通过 adb devices 查看。之后可在 Dev Menu 中开启 Fast Refresh，代码改动会自动重载。

  • 方式二：Wi-Fi
    手机与电脑连同一 Wi-Fi。首次需用 USB 安装一次 App；之后在 App 内打开 Dev Menu → Dev Settings → Debug server host & port for device，填入电脑 IP 与端口（如 10.0.1.1:8081），回到 Dev Menu 选择 Reload JS 即可无线调试。
    本机 IP 可在 macOS 系统设置 → 网络 中查看，或在终端执行 ifconfig | grep "inet " 查看（排除 127.0.0.1）。

参考：Running On Device - Androidopen in new window。

通过 Android Studio 来运行

在 Android Studio 左下角，找到并打开 Build Variants 选项卡，将 app module 的 Active Build Variant 切换至期待的环境（譬如 qaDebug）。

点击 Android Studio 上的运行按钮，即可安装和启动 App。

debug-2021-10-22-15-53-38

通过命令行来运行

启动终端，输入以下命令，即可在 qa 环境下运行：

npm run android

如果想要在 prod 环境下运行，需指定对应的 Gradle 安装任务（自定义 variant 如 prodDebug 对应任务名 installProdDebug）：

npx react-native run-android --tasks installProdDebug

仅需标准 release 构建时，可使用：npx react-native run-android --mode release。

运行 iOS 项目

在项目根目录打开终端，将工作目录切换到 ios 后再执行本节后续命令：

cd ios

我们使用 Bundleropen in new window 来确保无论项目在哪台机器上运行，所依赖的 Fastlaneopen in new window 和 Cocoapodsopen in new window 版本都是一致的。

安装 Fastlane 和 Cocoapods 等依赖

bundle install

Cocoapods 是 iOS 项目的依赖管理器，如同 Npm 之于 Node。

运行以下命令，安装依赖

bundle exec pod install

每当 iOS 项目依赖有更新时，需要再次运行 bundle exec pod install

iOS 项目在真机上运行，需要苹果开发者证书

首先注册一个 Apple IDopen in new window，也可以使用现有的 Apple ID，省去注册的麻烦。

将 Apple ID 提供给项目 owner，他会将你的 Apple ID 加入到苹果开发者账号，并授予合适的权限，留意你收到的邮件。

使用数据线连接 iOS 设备，前往 Signing & Capabilities，如果提示有签名问题，点击修复按钮即可。

debug-2021-10-22-15-35-35

通过 Xcode 来运行

在 Xcode 左上角，点击 Scheme 按钮，选择期待环境的 Scheme，譬如 MyApp qa。

点击 Xcode 的运行按钮，即可在 qa 环境下启动 iOS 应用。

debug-2021-10-22-15-43-28

通过命令行来运行

首先安装 ios-deploy

npm install -g ios-deploy

然后运行以下命令，即可在 qa 环境下运行

npx react-native run-ios --scheme 'MyApp qa' --configuration 'Debug qa' --device '你的 iPhone 名称'

连接 Metro

真机与电脑处于同一 Wi-Fi 时，摇一摇设备打开 Dev Menu 即可开启 Fast Refresh，代码改动会自动重载。

本机 IP 可在 系统设置 → 网络 或终端 ifconfig | grep "inet " 中查看（排除 127.0.0.1）。若出现红屏「Connection to http://localhost:8081/debugger-proxy?role=client timed out」：

  1. 确认手机和电脑在同一网络（带认证的公共 Wi-Fi 可能禁止设备互访，可改用手机热点或 Mac 通过 USB 共享网络）。
  2. 确认构建时嵌入的 IP 正确：在 Xcode 的 Report navigator 中选中最近一次 Build，搜索 IP=，后面的 IP 需与当前电脑 IP 一致。

参考：Running On Device - iOSopen in new window。

调试

应用运行起来后即可调试。注意：Release（生产）构建中，Dev Menu、LogBox、DevTools 等调试功能会被禁用，以下内容针对开发构建。

打开开发菜单

开发菜单提供重载、调试、性能监控等入口，可用以下方式打开：

  • 摇一摇设备（真机）或模拟器菜单：iOS 模拟器 Ctrl + Cmd + Z 或菜单 Device → Shake；Android 模拟器 Cmd + M（Windows/Linux 为 Ctrl + M）。
  • 运行 npm start 的终端里按 d。
  • Android 无法调出菜单时，可执行：adb shell input keyevent 82。

终端里也会提示：To reload the app press "r"、To open developer menu press "d"。

打开 React Native DevTools

在开发菜单中选择 Open DevTools，或在运行 Metro 的终端按 j，会打开 React Native 自带的调试界面。

DevTools 功能概览

DevTools 基于 Chrome DevTools 前端，提供：

  • Console：查看日志、过滤、执行 JS、Live Expressions 等。
  • Sources：查看源码、设置断点、单步执行；可用 debugger; 在代码里下断点，配合 Fast Refresh 立即生效。
  • Network（0.83+）：查看 fetch、XHR、<Image> 等网络请求及元数据。
  • Performance（0.83+）：录制 JS 执行、React 渲染、网络等性能时间线。
  • Memory：拍摄堆快照、查看 JS 内存占用。
  • React：组件树检查、Props/State 查看与修改、Profiler 录制渲染耗时。可在设置中开启「Highlight updates when components render」观察重绘。

若 DevTools 与设备断开（关 App、重装、崩溃、关 Metro 等），界面会提示「Debugging connection was closed」，可选择 Reconnect DevTools 重新连接。

LogBox

LogBox 会在应用内以红/黄条形式显示 console 的报错和警告：

  • 致命错误（如语法错误）：会全屏提示且无法关闭，修复后通过 Fast Refresh 或手动重载即可消失。
  • 一般错误与警告：以角标形式显示，点击可展开查看；在 DevTools 打开时，除致命错误外会优先在 DevTools Console 中展示。

可通过 API 忽略部分日志：LogBox.ignoreAllLogs() 关闭所有提示；LogBox.ignoreLogs([...]) 按内容或正则忽略指定日志（适合第三方库的噪音）。示例：

import { LogBox } from "react-native";

LogBox.ignoreLogs(["Warning: ..."]); // 按字符串匹配
LogBox.ignoreLogs([/GraphQL error: .*/]); // 按正则匹配

性能监控

在开发菜单中选择 Perf Monitor，可显示帧率、JS 线程等简要指标，供开发时参考。更精确的性能分析建议使用 Xcode 或 Android Studio 自带工具。

调试原生代码

  • 查看原生日志：在应用运行时，另开终端执行
    npx react-native log-android 或 npx react-native log-ios。
    Android 也可用：adb logcat "*:S" ReactNative:V ReactNativeJS:V。
  • 断点调试原生层：用 Android Studio 或 Xcode 打开工程，菜单 Run → Attach to Process...（Xcode 为 Debug → Attach to Process），选择正在运行的 React Native 应用进程，即可在原生代码中下断点调试。
  • 自定义 Native 日志：Android 在原生模块中用 Log.d("YourTag", message)，logcat 按 YourTag 过滤；iOS 用 NSLog 或 Swift 的 print，在 Xcode 控制台查看。

Release 构建调试（符号化堆栈）

Release 构建中若出现未处理的 JS 异常，堆栈可能是 minified 或 Hermes 字节码偏移（如 p@1:132161），需要 source map 和 metro-symbolicate 还原为可读的「文件:行号:函数名」。堆栈可从 adb logcat 保存、崩溃上报（如 Firebase Crashlytics）或用户反馈中获取，保存为 stacktrace.txt 后按下面步骤符号化。

  • 启用 source map
    • Android：在 android/app/build.gradle 的 react { ... } 中确保有 hermesFlags = ["-O", "-output-source-map"]（默认常已开启）。构建时 Metro 会输出 source map 路径，见构建日志。
    • iOS：默认不生成。在 Xcode 的「Bundle React Native code and images」Build Phase 中，在其它 export 之前增加：
      export SOURCEMAP_FILE="$(pwd)/../main.jsbundle.map"。
      构建后同样在 Metro/构建输出中确认 map 文件路径。
  • 使用 metro-symbolicate：
    • 从文件：npx metro-symbolicate <sourcemap 路径> < stacktrace.txt
    • 从 adb（Android）：adb logcat -d | npx metro-symbolicate <sourcemap 路径>

注意：用于符号化的 source map 必须与崩溃时的构建一一对应；输入需来自管道或重定向，不能直接键盘输入。

参考

上次更新: