react-native-expo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

React Native Expo (0.76-0.82+ / SDK 52+)

React Native Expo (0.76-0.82+ / SDK 52+)

Status: Production Ready Last Updated: 2026-01-21 Dependencies: Node.js 20.19.4+, Expo CLI, Xcode 16.1+ (iOS) Latest Versions: react-native@0.81.5, expo@~54.0.31, react@19.2.3

状态:可用于生产环境 最后更新:2026-01-21 依赖项:Node.js 20.19.4+、Expo CLI、Xcode 16.1+(iOS) 最新版本:react-native@0.81.5、expo@~54.0.31、react@19.2.3

Quick Start (15 Minutes)

快速开始(15分钟)

1. Create New Expo Project (RN 0.76+)

1. 创建新的Expo项目(RN 0.76+)

bash
undefined
bash
undefined

Create new Expo app with React Native 0.76+

创建使用React Native 0.76+的新Expo应用

npx create-expo-app@latest my-app
cd my-app
npx create-expo-app@latest my-app
cd my-app

Install latest dependencies

安装最新依赖项

npx expo install react-native@latest expo@latest

**Why this matters:**
- Expo SDK 52+ uses React Native 0.76+ with New Architecture enabled by default
- New Architecture is **mandatory** in React Native 0.82+ (cannot be disabled)
- Hermes is the only supported JavaScript engine (JSC removed from Expo Go)
npx expo install react-native@latest expo@latest

**为什么这很重要**:
- Expo SDK 52+默认使用启用了New Architecture的React Native 0.76+
- 在React Native 0.82+中,New Architecture是**强制启用**的(无法禁用)
- Hermes是唯一受支持的JavaScript引擎(Expo Go中已移除JSC)

2. Verify New Architecture is Enabled

2. 验证New Architecture已启用

bash
undefined
bash
undefined

Check if New Architecture is enabled (should be true by default)

检查New Architecture是否启用(默认应为true)

npx expo config --type introspect | grep newArchEnabled

**CRITICAL:**
- React Native 0.82+ **requires** New Architecture - legacy architecture completely removed
- If migrating from 0.75 or earlier, upgrade to 0.76-0.81 first to use the interop layer
- Never try to disable New Architecture in 0.82+ (build will fail)
npx expo config --type introspect | grep newArchEnabled

**关键提示**:
- React Native 0.82+**必须**使用New Architecture - 旧架构已完全移除
- 如果从0.75或更早版本迁移,请先升级到0.76-0.81以使用互操作层
- 切勿在0.82+中尝试禁用New Architecture(构建会失败)

3. Start Development Server

3. 启动开发服务器

bash
undefined
bash
undefined

Start Expo dev server

启动Expo开发服务器

npx expo start
npx expo start

Press 'i' for iOS simulator

按'i'启动iOS模拟器

Press 'a' for Android emulator

按'a'启动Android模拟器

Press 'j' to open React Native DevTools (NOT Chrome debugger!)

按'j'打开React Native DevTools(不要用Chrome调试器!)


**CRITICAL:**
- Old Chrome debugger removed in 0.79 - use React Native DevTools instead
- Metro terminal no longer streams `console.log()` - use DevTools Console
- Keyboard shortcuts 'a'/'i' work in CLI, not Metro terminal

---

**关键提示**:
- 0.79版本中已移除旧的Chrome调试器 - 请改用React Native DevTools
- Metro终端不再输出`console.log()`内容 - 请使用DevTools控制台
- 键盘快捷键'a'/'i'在CLI中生效,而非Metro终端

---

Critical Breaking Changes (Dec 2024+)

关键破坏性变更(2024年12月起)

🔴 New Architecture Mandatory (0.82+)

🔴 强制启用New Architecture(0.82+)

SDK Timeline:
  • Expo SDK 54 (React Native 0.81): Last release supporting Legacy Architecture
  • Expo SDK 55 (React Native 0.83): New Architecture mandatory, Legacy completely removed
What Changed:
  • 0.76-0.81 / SDK 52-54: New Architecture default, legacy frozen (no new features)
  • 0.82+ / SDK 55+: Legacy Architecture completely removed from codebase
Impact:
bash
undefined
SDK时间线
  • Expo SDK 54(React Native 0.81):最后一个支持旧架构的版本
  • Expo SDK 55(React Native 0.83):强制启用New Architecture,旧架构完全移除
变更内容
  • 0.76-0.81 / SDK 52-54:默认启用New Architecture,旧架构不再添加新功能
  • 0.82+ / SDK 55+:旧架构已从代码库中完全移除
影响
bash
undefined

This will FAIL in 0.82+ / SDK 55+:

在0.82+ / SDK 55+中,以下设置会导致构建失败:

gradle.properties (Android)

Android(gradle.properties)

newArchEnabled=false # ❌ Ignored, build fails
newArchEnabled=false # ❌ 会被忽略,构建失败

iOS

iOS

RCT_NEW_ARCH_ENABLED=0 # ❌ Ignored, build fails

**Migration Path:**
1. Upgrade to 0.76-0.81 / SDK 54 first (if on 0.75 or earlier)
2. Test with New Architecture enabled
3. Fix incompatible dependencies (Redux, i18n, CodePush, Reanimated v3 → v4)
4. Then upgrade to 0.82+ / SDK 55+

**Source:** [Expo SDK 54 Changelog](https://expo.dev/changelog/sdk-54)
RCT_NEW_ARCH_ENABLED=0 # ❌ 会被忽略,构建失败

**迁移路径**:
1. 先升级到0.76-0.81 / SDK 54(如果当前版本是0.75或更早)
2. 测试启用New Architecture的情况
3. 修复不兼容的依赖项(Redux、i18n、CodePush、Reanimated v3 → v4)
4. 然后升级到0.82+ / SDK 55+

**来源**:[Expo SDK 54更新日志](https://expo.dev/changelog/sdk-54)

🔴 propTypes Removed (React 19 / RN 0.78+)

🔴 propTypes已移除(React 19 / RN 0.78+)

What Changed: React 19 removed
propTypes
completely. No runtime validation, no warnings - silently ignored.
Before (Old Code):
typescript
import PropTypes from 'prop-types';

function MyComponent({ name, age }) {
  return <Text>{name} is {age}</Text>;
}

MyComponent.propTypes = {  // ❌ Silently ignored in React 19
  name: PropTypes.string.isRequired,
  age: PropTypes.number
};
After (Use TypeScript):
typescript
type MyComponentProps = {
  name: string;
  age?: number;
};

function MyComponent({ name, age }: MyComponentProps) {
  return <Text>{name} is {age}</Text>;
}
Migration:
bash
undefined
变更内容: React 19已完全移除
propTypes
。不再有运行时验证,也不会发出警告 - 会被静默忽略。
旧代码
typescript
import PropTypes from 'prop-types';

function MyComponent({ name, age }) {
  return <Text>{name} is {age}</Text>;
}

MyComponent.propTypes = {  // ❌ 在React 19中会被静默忽略
  name: PropTypes.string.isRequired,
  age: PropTypes.number
};
新代码(使用TypeScript)
typescript
type MyComponentProps = {
  name: string;
  age?: number;
};

function MyComponent({ name, age }: MyComponentProps) {
  return <Text>{name} is {age}</Text>;
}
迁移方法
bash
undefined

Use React 19 codemod to remove propTypes

使用React 19代码修改工具移除propTypes

npx @codemod/react-19 upgrade
undefined
npx @codemod/react-19 upgrade
undefined

🔴 forwardRef Deprecated (React 19)

🔴 forwardRef已弃用(React 19)

What Changed:
forwardRef
no longer needed - pass
ref
as a regular prop.
Before (Old Code):
typescript
import { forwardRef } from 'react';

const MyInput = forwardRef((props, ref) => {  // ❌ Deprecated
  return <TextInput ref={ref} {...props} />;
});
After (React 19):
typescript
function MyInput({ ref, ...props }) {  // ✅ ref is a regular prop
  return <TextInput ref={ref} {...props} />;
}
变更内容: 不再需要
forwardRef
- 将
ref
作为常规属性传递即可。
旧代码
typescript
import { forwardRef } from 'react';

const MyInput = forwardRef((props, ref) => {  // ❌ 已弃用
  return <TextInput ref={ref} {...props} />;
});
新代码(React 19)
typescript
function MyInput({ ref, ...props }) {  // ✅ ref是常规属性
  return <TextInput ref={ref} {...props} />;
}

🔴 Swift iOS Template Default (0.77+)

🔴 默认使用Swift iOS模板(0.77+)

What Changed: New projects use Swift
AppDelegate.swift
instead of Objective-C
AppDelegate.mm
.
Old Structure:
ios/MyApp/
├── main.m              # ❌ Removed
├── AppDelegate.h       # ❌ Removed
└── AppDelegate.mm      # ❌ Removed
New Structure:
swift
// ios/MyApp/AppDelegate.swift ✅
import UIKit
import React

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, ...) -> Bool {
    // App initialization
    return true
  }
}
Migration (0.76 → 0.77): When upgrading existing projects, you MUST add this line:
swift
// Add to AppDelegate.swift during migration
import React
import ReactCoreModules

RCTAppDependencyProvider.sharedInstance()  // ⚠️ CRITICAL: Must add this!
变更内容: 新项目使用Swift
AppDelegate.swift
而非Objective-C
AppDelegate.mm
旧结构
ios/MyApp/
├── main.m              # ❌ 已移除
├── AppDelegate.h       # ❌ 已移除
└── AppDelegate.mm      # ❌ 已移除
新结构
swift
// ios/MyApp/AppDelegate.swift ✅
import UIKit
import React

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, ...) -> Bool {
    // 应用初始化
    return true
  }
}
迁移(0.76 → 0.77): 升级现有项目时,必须添加以下代码:
swift
// 迁移时添加到AppDelegate.swift
import React
import ReactCoreModules

RCTAppDependencyProvider.sharedInstance()  // ⚠️ 关键:必须添加!

🔴 Metro Log Forwarding Removed (0.77+)

🔴 Metro日志转发已移除(0.77+)

What Changed: Metro terminal no longer streams
console.log()
output.
Before (0.76):
bash
undefined
变更内容: Metro终端不再输出
console.log()
内容。
旧版本(0.76)
bash
undefined

console.log() appeared in Metro terminal

console.log()内容会显示在Metro终端

$ npx expo start
LOG Hello from app! # ✅ Appeared here

**After (0.77+):**
```bash
$ npx expo start
LOG Hello from app! # ✅ 会显示在此处

**新版本(0.77+)**:
```bash

console.log() does NOT appear in Metro terminal

console.log()内容不会显示在Metro终端

$ npx expo start
$ npx expo start

(no logs shown) # ❌ Removed

(无日志输出) # ❌ 已移除

Workaround (temporary, will be removed):

临时解决方法(后续会移除):

$ npx expo start --client-logs # Shows logs, deprecated

**Solution:**
Use React Native DevTools Console instead (press 'j' in CLI).

**Source:** [React Native 0.77 Release Notes](https://reactnative.dev/blog/2025/01/14/release-0.77)
$ npx expo start --client-logs # 显示日志,但已弃用

**解决方案**:
改用React Native DevTools控制台(在CLI中按'j')。

**来源**:[React Native 0.77发布说明](https://reactnative.dev/blog/2025/01/14/release-0.77)

🔴 Chrome Debugger Removed (0.79+)

🔴 Chrome调试器已移除(0.79+)

What Changed: Old Chrome debugger (
chrome://inspect
) removed. Use React Native DevTools instead.
Old Method (Removed):
bash
undefined
变更内容: 已移除旧的Chrome调试器(
chrome://inspect
)。请改用React Native DevTools。
旧方法(已移除)
bash
undefined

❌ This no longer works:

❌ 此方法不再有效:

Open Dev Menu → "Debug" → Chrome DevTools opens

打开开发菜单 → "Debug" → 打开Chrome DevTools


**New Method (0.76+):**
```bash

**新方法(0.76+)**:
```bash

Press 'j' in CLI or Dev Menu → "Open React Native DevTools"

在CLI或开发菜单中按'j' → "Open React Native DevTools"

✅ Uses Chrome DevTools Protocol (CDP)

✅ 使用Chrome DevTools协议(CDP)

✅ Reliable breakpoints, watch values, stack inspection

✅ 可靠的断点、监视值、堆栈检查

✅ JS Console (replaces Metro logs)

✅ JS控制台(替代Metro日志)


**Limitations:**
- Third-party extensions not yet supported (Redux DevTools, etc.)
- Network inspector coming in 0.83 (late 2025)

**Source:** [React Native 0.79 Release Notes](https://reactnative.dev/blog/2025/04/release-0.79)

**限制**:
- 尚不支持第三方扩展(如Redux DevTools等)
- 网络检查器将于0.83版本(2025年末)推出

**来源**:[React Native 0.79发布说明](https://reactnative.dev/blog/2025/04/release-0.79)

🔴 JSC Engine Moved to Community (0.79+)

🔴 JSC引擎移至社区维护(0.79+)

What Changed: JavaScriptCore (JSC) first-party support removed from React Native 0.81+ core. Moved to community package.
Before (0.78):
  • Both Hermes and JSC bundled in React Native
  • JSC available in Expo Go
After (0.79+ / React Native 0.81+ / SDK 54):
bash
undefined
变更内容: 从React Native 0.81+核心中移除了JavaScriptCore(JSC)的官方支持,移至社区包维护。
旧版本(0.78)
  • React Native中同时包含Hermes和JSC
  • Expo Go中支持JSC
新版本(0.79+ / React Native 0.81+ / SDK 54)
bash
undefined

JSC removed from React Native core

JSC已从React Native核心中移除

If you still need JSC (rare):

如果仍需要JSC(罕见情况):

npm install @react-native-community/javascriptcore

**Expo Go:**
- SDK 52+: JSC completely removed from Expo Go
- Hermes only supported

**Note:** JSC will eventually be removed entirely from React Native.

**Source:** [Expo SDK 54 Changelog](https://expo.dev/changelog/sdk-54)
npm install @react-native-community/javascriptcore

**Expo Go**:
- SDK 52+:Expo Go中完全移除JSC
- 仅支持Hermes

**注意**:JSC最终将从React Native中完全移除。

**来源**:[Expo SDK 54更新日志](https://expo.dev/changelog/sdk-54)

🔴 Deep Imports Deprecated (0.80+)

🔴 深层导入已弃用(0.80+)

What Changed: Importing from internal paths will break.
Before (Old Code):
typescript
// ❌ Deep imports deprecated
import Button from 'react-native/Libraries/Components/Button';
import Platform from 'react-native/Libraries/Utilities/Platform';
After:
typescript
// ✅ Import only from 'react-native'
import { Button, Platform } from 'react-native';
变更内容: 从内部路径导入会导致错误。
旧代码
typescript
// ❌ 深层导入已弃用
import Button from 'react-native/Libraries/Components/Button';
import Platform from 'react-native/Libraries/Utilities/Platform';
新代码
typescript
// ✅ 仅从'react-native'导入
import { Button, Platform } from 'react-native';

🔴 Android Edge-to-Edge Mandatory (SDK 54+)

🔴 Android强制启用全屏显示(SDK 54+)

What Changed: Edge-to-edge display is enabled in all Android apps by default in SDK 54 and cannot be disabled.
Impact:
json
// app.json or app.config.js
{
  "expo": {
    "android": {
      // This setting is now IGNORED - edge-to-edge always enabled
      "edgeToEdgeEnabled": false  // ❌ No effect in SDK 54+
    }
  }
}
UI Impact: Content now extends behind system status bar and navigation bar. You must account for insets manually using
react-native-safe-area-context
.
Solution:
typescript
import { SafeAreaView } from 'react-native-safe-area-context';

function App() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      {/* Content respects system bars */}
    </SafeAreaView>
  );
}

变更内容: SDK 54及以上版本中,所有Android应用默认启用全屏显示,且无法禁用。
影响
json
// app.json或app.config.js
{
  "expo": {
    "android": {
      // 此设置现在会被忽略 - 始终启用全屏显示
      "edgeToEdgeEnabled": false  // ❌ 在SDK 54+中无效
    }
  }
}
UI影响: 内容现在会延伸到系统状态栏和导航栏后方。您必须使用
react-native-safe-area-context
手动处理内边距。
解决方案
typescript
import { SafeAreaView } from 'react-native-safe-area-context';

function App() {
  return (
    <SafeAreaView style={{ flex: 1 }}>
      {/* 内容会自动适配系统栏 */}
    </SafeAreaView>
  );
}

New Features (Post-Dec 2024)

新功能(2024年12月后)

CSS Properties (0.77+ New Architecture Only)

CSS属性(仅0.77+ New Architecture支持)

React Native now supports many CSS properties previously only available on web:
React Native现在支持许多此前仅在Web端可用的CSS属性:

1.
display: contents

1.
display: contents

Makes an element "invisible" but keeps its children in the layout:
typescript
<View style={{ display: 'contents' }}>
  {/* This View disappears, but Text still renders */}
  <Text>I'm still here!</Text>
</View>
Use case: Wrapper components that shouldn't affect layout.
使元素"不可见"但保留其子元素在布局中:
typescript
<View style={{ display: 'contents' }}>
  {/* 此View会消失,但Text仍会渲染 */}
  <Text>I'm still here!</Text>
</View>
使用场景:不影响布局的包装组件。

2.
boxSizing

2.
boxSizing

Control how width/height are calculated:
typescript
// Default: padding/border inside box
<View style={{
  boxSizing: 'border-box',  // Default
  width: 100,
  padding: 10,
  borderWidth: 2
  // Total width: 100 (padding/border inside)
}} />

// Content-box: padding/border outside
<View style={{
  boxSizing: 'content-box',
  width: 100,
  padding: 10,
  borderWidth: 2
  // Total width: 124 (100 + 20 padding + 4 border)
}} />
控制宽/高的计算方式:
typescript
// 默认值:内边距/边框包含在盒子内
<View style={{
  boxSizing: 'border-box',  // 默认值
  width: 100,
  padding: 10,
  borderWidth: 2
  // 总宽度:100(内边距/边框在内部)
}} />

// Content-box:内边距/边框在盒子外
<View style={{
  boxSizing: 'content-box',
  width: 100,
  padding: 10,
  borderWidth: 2
  // 总宽度:124(100 + 20内边距 + 4边框)
}} />

3.
mixBlendMode
+
isolation

3.
mixBlendMode
+
isolation

Blend layers like Photoshop:
typescript
<View style={{ backgroundColor: 'red' }}>
  <View style={{
    mixBlendMode: 'multiply',  // 16 modes available
    backgroundColor: 'blue'
    // Result: purple (red × blue)
  }} />
</View>

// Prevent unwanted blending:
<View style={{ isolation: 'isolate' }}>
  {/* Blending contained within this view */}
</View>
Available modes:
multiply
,
screen
,
overlay
,
darken
,
lighten
,
color-dodge
,
color-burn
,
hard-light
,
soft-light
,
difference
,
exclusion
,
hue
,
saturation
,
color
,
luminosity
像Photoshop一样混合图层:
typescript
<View style={{ backgroundColor: 'red' }}>
  <View style={{
    mixBlendMode: 'multiply',  // 支持16种模式
    backgroundColor: 'blue'
    // 结果:紫色(红色 × 蓝色)
  }} />
</View>

// 防止不必要的混合:
<View style={{ isolation: 'isolate' }}>
  {/* 混合效果仅在此View内生效 */}
</View>
支持的模式
multiply
,
screen
,
overlay
,
darken
,
lighten
,
color-dodge
,
color-burn
,
hard-light
,
soft-light
,
difference
,
exclusion
,
hue
,
saturation
,
color
,
luminosity

4.
outline
Properties

4.
outline
属性

Visual outline that doesn't affect layout (unlike
border
):
typescript
<View style={{
  outlineWidth: 2,
  outlineStyle: 'solid',      // solid | dashed | dotted
  outlineColor: 'blue',
  outlineOffset: 4,           // Space between element and outline
  outlineSpread: 2            // Expand outline beyond offset
}} />
Key difference: Outline doesn't change element size or trigger layout recalculations.
不影响布局的视觉轮廓(与
border
不同):
typescript
<View style={{
  outlineWidth: 2,
  outlineStyle: 'solid',      // solid | dashed | dotted
  outlineColor: 'blue',
  outlineOffset: 4,           // 元素与轮廓之间的间距
  outlineSpread: 2            // 轮廓超出偏移量的扩展范围
}} />
关键区别:轮廓不会改变元素大小或触发布局重新计算。

Android XML Drawables (0.78+)

Android XML可绘制资源(0.78+)

Use native Android vector drawables (XML) as Image sources:
typescript
// Load XML drawable at build time
import MyIcon from './assets/my_icon.xml';

<Image
  source={MyIcon}
  style={{ width: 40, height: 40 }}
/>

// Or with require:
<Image
  source={require('./assets/my_icon.xml')}
  style={{ width: 40, height: 40 }}
/>
Benefits:
  • Scalable vector graphics (resolution-independent)
  • Smaller APK size vs PNG
  • Off-thread decoding (better performance)
Constraints:
  • Build-time resources only (no network loading)
  • Android only (iOS still uses SF Symbols or PNG)
将原生Android矢量可绘制资源(XML)用作Image源:
typescript
// 构建时加载XML可绘制资源
import MyIcon from './assets/my_icon.xml';

<Image
  source={MyIcon}
  style={{ width: 40, height: 40 }}
/>

// 或使用require:
<Image
  source={require('./assets/my_icon.xml')}
  style={{ width: 40, height: 40 }}
/>
优势
  • 可缩放矢量图形(与分辨率无关)
  • 相比PNG,APK体积更小
  • 后台线程解码(性能更好)
限制
  • 仅支持构建时资源(不支持网络加载)
  • 仅支持Android(iOS仍使用SF Symbols或PNG)

React 19 New Hooks

React 19新Hook

1.
useActionState
(replaces form patterns)

1.
useActionState
(替代表单模式)

typescript
import { useActionState } from 'react';

function MyForm() {
  const [state, submitAction, isPending] = useActionState(
    async (prevState, formData) => {
      // Async form submission
      const result = await api.submit(formData);
      return result;
    },
    { message: '' }  // Initial state
  );

  return (
    <form action={submitAction}>
      <TextInput name="email" />
      <Button disabled={isPending}>
        {isPending ? 'Submitting...' : 'Submit'}
      </Button>
      {state.message && <Text>{state.message}</Text>}
    </form>
  );
}
typescript
import { useActionState } from 'react';

function MyForm() {
  const [state, submitAction, isPending] = useActionState(
    async (prevState, formData) => {
      // 异步表单提交
      const result = await api.submit(formData);
      return result;
    },
    { message: '' }  // 初始状态
  );

  return (
    <form action={submitAction}>
      <TextInput name="email" />
      <Button disabled={isPending}>
        {isPending ? '提交中...' : '提交'}
      </Button>
      {state.message && <Text>{state.message}</Text>}
    </form>
  );
}

2.
useOptimistic
(optimistic UI updates)

2.
useOptimistic
(乐观UI更新)

typescript
import { useOptimistic } from 'react';

function LikeButton({ postId, initialLikes }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (currentLikes, amount) => currentLikes + amount
  );

  async function handleLike() {
    addOptimisticLike(1);  // Update UI immediately
    await api.like(postId);  // Then update server
  }

  return (
    <Button onPress={handleLike}>
      ❤️ {optimisticLikes}
    </Button>
  );
}
typescript
import { useOptimistic } from 'react';

function LikeButton({ postId, initialLikes }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (currentLikes, amount) => currentLikes + amount
  );

  async function handleLike() {
    addOptimisticLike(1);  // 立即更新UI
    await api.like(postId);  // 然后更新服务器
  }

  return (
    <Button onPress={handleLike}>
      ❤️ {optimisticLikes}
    </Button>
  );
}

3.
use
(read promises/contexts during render)

3.
use
(渲染时读取promise/context)

typescript
import { use } from 'react';

function UserProfile({ userPromise }) {
  // Read promise directly during render (suspends if pending)
  const user = use(userPromise);

  return <Text>{user.name}</Text>;
}
typescript
import { use } from 'react';

function UserProfile({ userPromise }) {
  // 渲染时直接读取promise(pending时会暂停)
  const user = use(userPromise);

  return <Text>{user.name}</Text>;
}

React Native DevTools (0.76+)

React Native DevTools(0.76+)

Access:
  • Press
    j
    in CLI
  • Or open Dev Menu → "Open React Native DevTools"
Features:
  • ✅ Reliable breakpoints (unlike old Chrome debugger)
  • ✅ Watch values, call stack inspection
  • ✅ JS Console (replaces Metro logs)
  • ✅ Chrome DevTools Protocol (CDP) based
  • ⏳ Network inspector (coming in 0.83)
  • ❌ Third-party extensions not yet supported

访问方式
  • 在CLI中按
    j
  • 或打开开发菜单 → "Open React Native DevTools"
功能
  • ✅ 可靠的断点(与旧Chrome调试器不同)
  • ✅ 监视值、调用堆栈检查
  • ✅ JS控制台(替代Metro日志)
  • ✅ 基于Chrome DevTools协议(CDP)
  • ⏳ 网络检查器(将于0.83版本推出)
  • ❌ 尚不支持第三方扩展

Known Issues Prevention

已知问题预防

This skill prevents 16 documented issues:
本指南可避免16种已记录的问题:

Issue #1: propTypes Silently Ignored

问题#1:propTypes被静默忽略

Error: No error -
propTypes
just doesn't work Source: React 19 Upgrade Guide Why It Happens: React 19 removed runtime propTypes validation Prevention: Use TypeScript instead, run
npx @codemod/react-19 upgrade
to remove
错误表现:无错误 -
propTypes
只是不生效 来源React 19升级指南 原因:React 19移除了运行时propTypes验证 预防方法:改用TypeScript,运行
npx @codemod/react-19 upgrade
移除propTypes

Issue #2: forwardRef Deprecated Warning

问题#2:forwardRef弃用警告

Error:
Warning: forwardRef is deprecated
Source: React 19 Upgrade Guide Why It Happens: React 19 allows
ref
as a regular prop Prevention: Remove
forwardRef
wrapper, pass
ref
as prop directly
错误表现
Warning: forwardRef is deprecated
来源React 19升级指南 原因:React 19允许将
ref
作为常规属性传递 预防方法:移除
forwardRef
包装器,直接将
ref
作为属性传递

Issue #3: New Architecture Cannot Be Disabled (0.82+)

问题#3:0.82+中无法禁用New Architecture

Error: Build fails with
newArchEnabled=false
Source: React Native 0.82 Release Notes Why It Happens: Legacy architecture completely removed from codebase Prevention: Migrate to New Architecture before upgrading to 0.82+
错误表现:设置
newArchEnabled=false
时构建失败 来源React Native 0.82发布说明 原因:旧架构已从代码库中完全移除 预防方法:升级到0.82+前先迁移至New Architecture

Issue #4: "Fabric component descriptor not found"

问题#4:"Fabric component descriptor not found"

Error:
Fabric component descriptor provider not found for component
Source: New Architecture Migration Guide Why It Happens: Component not compatible with New Architecture (Fabric) Prevention: Update library to New Architecture version, or use interop layer (0.76-0.81)
错误表现
Fabric component descriptor provider not found for component
来源New Architecture迁移指南 原因:组件与New Architecture(Fabric)不兼容 预防方法:将库更新到支持New Architecture的版本,或使用互操作层(0.76-0.81)

Issue #5: "TurboModule not registered"

问题#5:"TurboModule not registered"

Error:
TurboModule '[ModuleName]' not found
Source: New Architecture Migration Guide Why It Happens: Native module needs New Architecture support (TurboModules) Prevention: Update library to support TurboModules, or use interop layer (0.76-0.81)
错误表现
TurboModule '[ModuleName]' not found
来源New Architecture迁移指南 原因:原生模块需要支持New Architecture(TurboModules) 预防方法:将库更新到支持TurboModules的版本,或使用互操作层(0.76-0.81)

Issue #6: Swift AppDelegate Missing RCTAppDependencyProvider

问题#6:Swift AppDelegate缺少RCTAppDependencyProvider

Error:
RCTAppDependencyProvider not found
Source: React Native 0.77 Release Notes Why It Happens: When migrating from Objective-C to Swift template Prevention: Add
RCTAppDependencyProvider.sharedInstance()
to AppDelegate.swift
错误表现
RCTAppDependencyProvider not found
来源React Native 0.77发布说明 原因:从Objective-C模板迁移到Swift模板时 预防方法:在AppDelegate.swift中添加
RCTAppDependencyProvider.sharedInstance()

Issue #7: Metro Logs Not Appearing

问题#7:Metro日志不显示

Error:
console.log()
doesn't show in terminal Source: React Native 0.77 Release Notes Why It Happens: Metro log forwarding removed in 0.77 Prevention: Use React Native DevTools Console (press 'j'), or
--client-logs
flag (temporary)
错误表现
console.log()
内容不显示在终端中 来源React Native 0.77发布说明 原因:0.77版本中移除了Metro日志转发 预防方法:使用React Native DevTools控制台(按'j'),或使用
--client-logs
标志(临时解决方法)

Issue #8: Chrome Debugger Not Working

问题#8:Chrome调试器无法工作

Error: Chrome DevTools doesn't connect Source: React Native 0.79 Release Notes Why It Happens: Old Chrome debugger removed in 0.79 Prevention: Use React Native DevTools instead (press 'j')
错误表现:Chrome DevTools无法连接 来源React Native 0.79发布说明 原因:0.79版本中移除了旧Chrome调试器 预防方法:改用React Native DevTools(按'j')

Issue #9: Deep Import Errors

问题#9:深层导入错误

Error:
Module not found: react-native/Libraries/...
Source: React Native 0.80 Release Notes Why It Happens: Internal paths deprecated, strict API enforced Prevention: Import only from
'react-native'
, not deep paths
错误表现
Module not found: react-native/Libraries/...
来源React Native 0.80发布说明 原因:内部路径已弃用,强制执行严格API 预防方法:仅从
'react-native'
导入,不要使用深层路径

Issue #10: Redux Store Crashes with New Architecture

问题#10:Redux Store在New Architecture下崩溃

Error: App crashes on Redux store creation Source: Redux Toolkit Migration Guide Why It Happens: Old
redux
+
redux-thunk
incompatible with New Architecture Prevention: Use Redux Toolkit (
@reduxjs/toolkit
) instead
错误表现:应用在创建Redux Store时崩溃 来源Redux Toolkit迁移指南 原因:旧版
redux
+
redux-thunk
与New Architecture不兼容 预防方法:改用Redux Toolkit(
@reduxjs/toolkit

Issue #11: i18n-js Unreliable with New Architecture

问题#11:i18n-js在New Architecture下不可靠

Error: Translations not updating, or app crashes Source: Community reports (GitHub issues) Why It Happens:
i18n-js
not fully compatible with New Architecture Prevention: Use
react-i18next
instead
错误表现:翻译不更新,或应用崩溃 来源:社区报告(GitHub issues) 原因
i18n-js
未完全兼容New Architecture 预防方法:改用
react-i18next

Issue #12: CodePush Crashes on Android

问题#12:CodePush在Android上崩溃

Error: Android crashes looking for bundle named
null
Source: CodePush GitHub Issues Why It Happens: Known incompatibility with New Architecture Prevention: Avoid CodePush with New Architecture, or wait for official support
错误表现:Android应用崩溃,寻找名为
null
的包 来源CodePush GitHub Issues 原因:与New Architecture存在已知不兼容问题 预防方法:在New Architecture中避免使用CodePush,或等待官方支持

Issue #13: expo-file-system Legacy API Removed (SDK 55+)

问题#13:expo-file-system旧版API已移除(SDK 55+)

Error:
Module not found: expo-file-system/legacy
Source: Expo SDK 54 Changelog, GitHub Issue #39056 Why It Happens: Legacy API removed in SDK 55, must migrate to new File/Directory class API Prevention: Migrate to new API before upgrading to SDK 55
Migration Timeline:
  • SDK 53 and earlier: Legacy API at
    expo-file-system
  • SDK 54: Legacy API at
    expo-file-system/legacy
    , new API at
    expo-file-system
    (default)
  • SDK 55: Legacy API removed completely
Old Code (SDK 54 with legacy import):
typescript
import * as FileSystem from 'expo-file-system/legacy';
await FileSystem.writeAsStringAsync(uri, content);
New Code (SDK 54+ new API):
typescript
import { File } from 'expo-file-system';
const file = new File(uri);
await file.writeString(content);
错误表现
Module not found: expo-file-system/legacy
来源Expo SDK 54更新日志, GitHub Issue #39056 原因:SDK 55中移除了旧版API,必须迁移至新的File/Directory类API 预防方法:升级到SDK 55前先迁移至新API
迁移时间线
  • SDK 53及更早:旧版API位于
    expo-file-system
  • SDK 54:旧版API位于
    expo-file-system/legacy
    ,新版API位于
    expo-file-system
    (默认)
  • SDK 55:完全移除旧版API
旧代码(SDK 54使用旧版导入)
typescript
import * as FileSystem from 'expo-file-system/legacy';
await FileSystem.writeAsStringAsync(uri, content);
新代码(SDK 54+新版API)
typescript
import { File } from 'expo-file-system';
const file = new File(uri);
await file.writeString(content);

Issue #14: expo-av Removed (SDK 55+)

问题#14:expo-av已移除(SDK 55+)

Error:
Module not found: expo-av
Source: Expo SDK 54 Changelog, expo-av GitHub Why It Happens: Package deprecated in SDK 53, removed in SDK 55 Prevention: Migrate to expo-audio and expo-video before SDK 55
Migration Timeline:
  • SDK 52:
    expo-video
    introduced
  • SDK 53:
    expo-audio
    introduced,
    expo-av
    deprecated
  • SDK 54: Last release with
    expo-av
    (no patches)
  • SDK 55:
    expo-av
    removed
Migration - Audio:
typescript
// OLD: expo-av
import { Audio } from 'expo-av';
const { sound } = await Audio.Sound.createAsync(require('./audio.mp3'));
await sound.playAsync();

// NEW: expo-audio
import { useAudioPlayer } from 'expo-audio';
const player = useAudioPlayer(require('./audio.mp3'));
player.play();
Migration - Video:
typescript
// OLD: expo-av
import { Video } from 'expo-av';
<Video source={require('./video.mp4')} />

// NEW: expo-video
import { VideoView } from 'expo-video';
<VideoView source={require('./video.mp4')} />
错误表现
Module not found: expo-av
来源Expo SDK 54更新日志, expo-av GitHub 原因:SDK 53中弃用该包,SDK 55中移除 预防方法:在SDK 55前迁移至expo-audio和expo-video
迁移时间线
  • SDK 52:推出
    expo-video
  • SDK 53:推出
    expo-audio
    ,弃用
    expo-av
  • SDK 54:最后一个包含
    expo-av
    的版本(不再提供补丁)
  • SDK 55:移除
    expo-av
迁移 - 音频
typescript
// 旧版:expo-av
import { Audio } from 'expo-av';
const { sound } = await Audio.Sound.createAsync(require('./audio.mp3'));
await sound.playAsync();

// 新版:expo-audio
import { useAudioPlayer } from 'expo-audio';
const player = useAudioPlayer(require('./audio.mp3'));
player.play();
迁移 - 视频
typescript
// 旧版:expo-av
import { Video } from 'expo-av';
<Video source={require('./video.mp4')} />

// 新版:expo-video
import { VideoView } from 'expo-video';
<VideoView source={require('./video.mp4')} />

Issue #15: Reanimated v4 Requires New Architecture

问题#15:Reanimated v4需要New Architecture

Error: Build fails or crashes with Reanimated v4 on Legacy Architecture Source: Expo SDK 54 FYI Why It Happens: Reanimated v4 exclusively requires New Architecture Prevention: Use Reanimated v3 with Legacy Architecture, or migrate to New Architecture first
Version Matrix:
Reanimated VersionArchitecture SupportExpo SDK
v3Legacy + New ArchitectureSDK 52-54
v4New Architecture ONLYSDK 54+
NativeWind Incompatibility:
bash
undefined
错误表现:在旧架构下使用Reanimated v4会导致构建失败或崩溃 来源Expo SDK 54 FYI 原因:Reanimated v4仅支持New Architecture 预防方法:在旧架构中使用Reanimated v3,或先迁移至New Architecture
版本矩阵
Reanimated版本架构支持Expo SDK
v3旧架构 + New ArchitectureSDK 52-54
v4仅New ArchitectureSDK 54+
NativeWind不兼容问题
bash
// 截至2026年1月,NativeWind尚不支持Reanimated v4
// 如果使用NativeWind,必须保留Reanimated v3
npm install react-native-reanimated@^3
迁移至v4(仅New Architecture支持)
  1. 安装
    react-native-worklets
    (v4必需)
  2. 遵循官方Reanimated v3 → v4迁移指南
  3. 如果使用
    babel-preset-expo
    ,可跳过babel.config.js的修改(自动配置)

NativeWind does not support Reanimated v4 yet (as of Jan 2026)

问题#16:iOS在Hermes + New Architecture(SDK 54)下启动崩溃 - 社区发现

If using NativeWind, must stay on Reanimated v3

npm install react-native-reanimated@^3

**Migration to v4 (New Architecture only):**
1. Install `react-native-worklets` (required for v4)
2. Follow [official Reanimated v3 → v4 migration guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/)
3. Skip babel.config.js changes if using `babel-preset-expo` (auto-configured)
错误表现
hermes::vm::JSObject::putComputed_RJS
hermes::vm::arrayPrototypePush
来源GitHub Issue #41824, Medium文章 已验证:可复现 原因:在iOS上使用New Architecture时,Expo Updates需要在Podfile中显式设置
:hermes_enabled
标志 预防方法:在ios/Podfile中添加显式的Hermes标志
触发条件
  • Expo SDK 54
  • 启用New Architecture
  • 启用Hermes(默认)
  • 使用
    expo-updates
  • 仅iOS(Android不受影响)
解决方法
ruby
undefined

Issue #16: iOS Crashes on Launch with Hermes + New Architecture (SDK 54) - Community-sourced

ios/Podfile

Error:
hermes::vm::JSObject::putComputed_RJS
hermes::vm::arrayPrototypePush
Source: GitHub Issue #41824, Medium Post Verified: Reproduction available Why It Happens: Expo Updates requires explicit
:hermes_enabled
flag in Podfile when using New Architecture on iOS Prevention: Add explicit Hermes flag to ios/Podfile
Conditions:
  • Expo SDK 54
  • New Architecture enabled
  • Hermes enabled (default)
  • Using
    expo-updates
  • iOS only (Android unaffected)
Workaround:
ruby
undefined
use_frameworks! :linkage => :static ENV['HERMES_ENABLED'] = '1' # ⚠️ 关键:在New Arch + expo-updates下必须显式设置

**注意**:这是社区发现的问题,有可复现的仓库,但尚未在Expo更新日志中正式记录。

---

ios/Podfile

迁移指南:0.72-0.75 → 0.82+

步骤1:先升级到互操作层(0.76-0.81)

use_frameworks! :linkage => :static ENV['HERMES_ENABLED'] = '1' # ⚠️ CRITICAL: Must be explicit with New Arch + expo-updates

**Note:** This is a community-sourced finding with reproduction repository, not yet officially documented in Expo changelog.

---
原因:如果使用旧架构,无法直接跳转到0.82 - 会失去互操作层。
bash
undefined

Migration Guide: 0.72-0.75 → 0.82+

检查当前版本

Step 1: Upgrade to Interop Layer First (0.76-0.81)

Why: Can't skip directly to 0.82 if using legacy architecture - you'll lose the interop layer.
bash
undefined
npx react-native --version

Check current version

先升级到0.81(最后一个支持互操作层的版本)

npx react-native --version
npm install react-native@0.81 npx expo install --fix
undefined

Upgrade to 0.81 first (last version with interop layer)

步骤2:启用New Architecture(如果尚未启用)

npm install react-native@0.81 npx expo install --fix
undefined
bash
undefined

Step 2: Enable New Architecture (if not already)

Android(gradle.properties)

bash
undefined
newArchEnabled=true

Android (gradle.properties)

iOS

newArchEnabled=true
RCT_NEW_ARCH_ENABLED=1 bundle exec pod install

iOS

重新构建

RCT_NEW_ARCH_ENABLED=1 bundle exec pod install
npm run ios npm run android
undefined

Rebuild

步骤3:修复不兼容的依赖项

npm run ios npm run android
undefined
常见不兼容项
bash
undefined

Step 3: Fix Incompatible Dependencies

用Redux Toolkit替代Redux

Common incompatibilities:
bash
undefined
npm uninstall redux redux-thunk npm install @reduxjs/toolkit react-redux

Replace Redux with Redux Toolkit

用react-i18next替代i18n-js

npm uninstall redux redux-thunk npm install @reduxjs/toolkit react-redux
npm uninstall i18n-js npm install react-i18next i18next

Replace i18n-js with react-i18next

更新React Navigation(如果版本较旧)

npm uninstall i18n-js npm install react-i18next i18next
npm install @react-navigation/native@latest
undefined

Update React Navigation (if old version)

步骤4:全面测试

npm install @react-navigation/native@latest
undefined
bash
undefined

Step 4: Test Thoroughly

在两个平台上运行

bash
undefined
npm run ios npm run android

Run on both platforms

测试所有功能:

- 导航

- 状态管理(Redux)

- API调用

- 深度链接

- 推送通知

npm run ios npm run android
undefined

Test all features:

步骤5:迁移至React 19(如果升级到0.78+)

- Navigation

- State management (Redux)

- API calls

- Deep linking

- Push notifications

undefined
bash
undefined

Step 5: Migrate to React 19 (if upgrading to 0.78+)

运行React 19代码修改工具

bash
undefined
npx @codemod/react-19 upgrade

Run React 19 codemod

手动验证:

- 移除所有propTypes声明

- 移除forwardRef包装器

- 更新到新Hook(useActionState、useOptimistic)

npx @codemod/react-19 upgrade
undefined

Manually verify:

步骤6:升级到0.82+

- Remove all propTypes declarations

- Remove forwardRef wrappers

- Update to new hooks (useActionState, useOptimistic)

undefined
bash
undefined

Step 6: Upgrade to 0.82+

仅在New Architecture测试通过后执行!

bash
undefined
npm install react-native@0.82 npx expo install --fix

Only after testing with New Architecture enabled!

重新构建

npm install react-native@0.82 npx expo install --fix
npm run ios npm run android
undefined

Rebuild

步骤7:将iOS迁移到Swift(如果是新项目)

npm run ios npm run android
undefined
新项目(0.77+)默认使用Swift。对于现有项目:
bash
undefined

Step 7: Migrate iOS to Swift (if new project)

遵循升级助手

选择:0.76 → 0.77

关键:在AppDelegate.swift中添加以下代码

New projects (0.77+) use Swift by default. For existing projects:
bash
undefined
RCTAppDependencyProvider.sharedInstance()

---

Follow upgrade helper

常见模式

模式1:使用新Hook的条件渲染

Select: 0.76 → 0.77

CRITICAL: Add this line to AppDelegate.swift

RCTAppDependencyProvider.sharedInstance()

---
typescript
import { useActionState } from 'react';

function LoginForm() {
  const [state, loginAction, isPending] = useActionState(
    async (prevState, formData) => {
      try {
        const user = await api.login(formData);
        return { success: true, user };
      } catch (error) {
        return { success: false, error: error.message };
      }
    },
    { success: false }
  );

  return (
    <View>
      <form action={loginAction}>
        <TextInput name="email" placeholder="邮箱" />
        <TextInput name="password" secureTextEntry />
        <Button disabled={isPending}>
          {isPending ? '登录中...' : '登录'}
        </Button>
      </form>
      {!state.success && state.error && (
        <Text style={{ color: 'red' }}>{state.error}</Text>
      )}
    </View>
  );
}
使用场景:带有加载/错误状态的表单提交

Common Patterns

模式2:用TypeScript替代propTypes

Pattern 1: Conditional Rendering with New Hooks

typescript
import { useActionState } from 'react';

function LoginForm() {
  const [state, loginAction, isPending] = useActionState(
    async (prevState, formData) => {
      try {
        const user = await api.login(formData);
        return { success: true, user };
      } catch (error) {
        return { success: false, error: error.message };
      }
    },
    { success: false }
  );

  return (
    <View>
      <form action={loginAction}>
        <TextInput name="email" placeholder="Email" />
        <TextInput name="password" secureTextEntry />
        <Button disabled={isPending}>
          {isPending ? 'Logging in...' : 'Login'}
        </Button>
      </form>
      {!state.success && state.error && (
        <Text style={{ color: 'red' }}>{state.error}</Text>
      )}
    </View>
  );
}
When to use: Form submission with loading/error states
typescript
// 用TypeScript定义属性类型
type ButtonProps = {
  title: string;
  onPress: () => void;
  disabled?: boolean;
  variant?: 'primary' | 'secondary';
};

function Button({ title, onPress, disabled = false, variant = 'primary' }: ButtonProps) {
  return (
    <Pressable
      onPress={onPress}
      disabled={disabled}
      style={[styles.button, styles[variant]]}
    >
      <Text style={styles.text}>{title}</Text>
    </Pressable>
  );
}
使用场景:始终使用(React 19中已移除propTypes)

Pattern 2: TypeScript Instead of propTypes

模式3:使用新CSS实现视觉效果

typescript
// Define prop types with TypeScript
type ButtonProps = {
  title: string;
  onPress: () => void;
  disabled?: boolean;
  variant?: 'primary' | 'secondary';
};

function Button({ title, onPress, disabled = false, variant = 'primary' }: ButtonProps) {
  return (
    <Pressable
      onPress={onPress}
      disabled={disabled}
      style={[styles.button, styles[variant]]}
    >
      <Text style={styles.text}>{title}</Text>
    </Pressable>
  );
}
When to use: Always (propTypes removed in React 19)
typescript
// 带发光效果的按钮,使用outline和混合模式
function GlowButton({ title, onPress }) {
  return (
    <Pressable
      onPress={onPress}
      style={{
        backgroundColor: '#3b82f6',
        padding: 16,
        borderRadius: 8,
        // Outline不影响布局
        outlineWidth: 2,
        outlineColor: '#60a5fa',
        outlineOffset: 4,
        // 与背景混合
        mixBlendMode: 'screen',
        isolation: 'isolate'
      }}
    >
      <Text style={{ color: 'white', fontWeight: 'bold' }}>
        {title}
      </Text>
    </Pressable>
  );
}
使用场景:不影响布局的视觉效果(仅New Architecture支持)

Pattern 3: New CSS for Visual Effects

使用捆绑资源

脚本(scripts/)

typescript
// Glowing button with outline and blend mode
function GlowButton({ title, onPress }) {
  return (
    <Pressable
      onPress={onPress}
      style={{
        backgroundColor: '#3b82f6',
        padding: 16,
        borderRadius: 8,
        // Outline doesn't affect layout
        outlineWidth: 2,
        outlineColor: '#60a5fa',
        outlineOffset: 4,
        // Blend with background
        mixBlendMode: 'screen',
        isolation: 'isolate'
      }}
    >
      <Text style={{ color: 'white', fontWeight: 'bold' }}>
        {title}
      </Text>
    </Pressable>
  );
}
When to use: Visual effects without affecting layout (New Architecture only)

check-rn-version.sh - 检测React Native版本并警告架构要求
示例用法
bash
./scripts/check-rn-version.sh

Using Bundled Resources

输出:✅ React Native 0.82 - 必须使用New Architecture

Scripts (scripts/)

输出:⚠️ React Native 0.75 - 建议升级到0.76+

check-rn-version.sh - Detects React Native version and warns about architecture requirements
Example Usage:
bash
./scripts/check-rn-version.sh
undefined

Output: ✅ React Native 0.82 - New Architecture mandatory

参考资料(references/)

Output: ⚠️ React Native 0.75 - Upgrade to 0.76+ recommended

undefined
react-19-migration.md - 详细的React 19破坏性变更和迁移步骤
new-architecture-errors.md - 启用New Architecture时的常见构建错误
expo-sdk-52-breaking.md - Expo SDK 52+特有的破坏性变更
Claude应在何时加载这些资源:遇到迁移错误、构建失败或React 19相关的详细问题时

References (references/)

资源(assets/)

react-19-migration.md - Detailed React 19 breaking changes and migration steps
new-architecture-errors.md - Common build errors when enabling New Architecture
expo-sdk-52-breaking.md - Expo SDK 52+ specific breaking changes
When Claude should load these: When encountering migration errors, build failures, or detailed React 19 questions
new-arch-decision-tree.md - 选择React Native版本的决策树
css-features-cheatsheet.md - 新CSS属性的完整示例

Assets (assets/)

Expo SDK 52+细节

破坏性变更

new-arch-decision-tree.md - Decision tree for choosing React Native version
css-features-cheatsheet.md - Complete examples of new CSS properties

Expo Go中移除JSC
json
// 在Expo Go(SDK 52+)中不再生效:
{
  "jsEngine": "jsc"  // ❌ 会被忽略,仅支持Hermes
}
Expo Go中移除Google Maps(SDK 53+)
bash
undefined

Expo SDK 52+ Specifics

必须使用自定义开发客户端来使用Google Maps

Breaking Changes

JSC Removed from Expo Go:
json
// This no longer works in Expo Go (SDK 52+):
{
  "jsEngine": "jsc"  // ❌ Ignored, Hermes only
}
Google Maps Removed from Expo Go (SDK 53+):
bash
undefined
npx expo install expo-dev-client npx expo run:android

**推送通知警告**:
Expo Go会对推送通知显示警告 - 生产测试请使用自定义开发客户端。

Must use custom dev client for Google Maps

新功能(SDK 52)

npx expo install expo-dev-client npx expo run:android

**Push Notifications Warning:**
Expo Go shows warnings for push notifications - use custom dev client for production testing.
expo/fetch(兼容WinterCG)
typescript
import { fetch } from 'expo/fetch';

// 符合标准的fetch,适用于Workers/Edge运行时
const response = await fetch('https://api.example.com/data');
React Navigation v7
bash
npm install @react-navigation/native@^7.0.0

New Features (SDK 52)

官方文档

expo/fetch (WinterCG-compliant):
typescript
import { fetch } from 'expo/fetch';

// Standards-compliant fetch for Workers/Edge runtimes
const response = await fetch('https://api.example.com/data');
React Navigation v7:
bash
npm install @react-navigation/native@^7.0.0

Official Documentation

包版本(2026-01-21已验证)

构建工具要求(SDK 54+)
  • Xcode:最低16.1,推荐16
  • Node.js:最低20.19.4
  • iOS部署目标:iOS 15.1+
json
{
  "dependencies": {
    "react": "^19.2.3",
    "react-native": "^0.81.5",
    "expo": "~54.0.31",
    "@react-navigation/native": "^7.0.0",
    "@reduxjs/toolkit": "^2.0.0",
    "react-i18next": "^15.0.0"
  },
  "devDependencies": {
    "@types/react": "^19.0.0",
    "typescript": "^5.7.0"
  }
}

Package Versions (Verified 2026-01-21)

故障排除

问题:构建失败,提示"Fabric component descriptor not found"

Build Tool Requirements (SDK 54+):
  • Xcode: Minimum 16.1, Xcode 16 recommended
  • Node.js: Minimum 20.19.4
  • iOS Deployment Target: iOS 15.1+
json
{
  "dependencies": {
    "react": "^19.2.3",
    "react-native": "^0.81.5",
    "expo": "~54.0.31",
    "@react-navigation/native": "^7.0.0",
    "@reduxjs/toolkit": "^2.0.0",
    "react-i18next": "^15.0.0"
  },
  "devDependencies": {
    "@types/react": "^19.0.0",
    "typescript": "^5.7.0"
  }
}

解决方案:库与New Architecture不兼容。检查库文档是否支持New Architecture,或使用互操作层(仅0.76-0.81支持)。

Troubleshooting

问题:"propTypes is not a function"错误

Problem: Build fails with "Fabric component descriptor not found"

Solution: Library not compatible with New Architecture. Check library docs for New Architecture support, or use interop layer (0.76-0.81 only).
解决方案:React 19已移除propTypes。改用TypeScript进行类型检查。运行
npx @codemod/react-19 upgrade

Problem: "propTypes is not a function" error

问题:console.log()内容不显示在Metro终端

Solution: React 19 removed propTypes. Use TypeScript for type checking instead. Run
npx @codemod/react-19 upgrade
.
解决方案:0.77版本中移除了Metro日志转发。使用React Native DevTools控制台(按'j')或
npx expo start --client-logs
(临时解决方法)。

Problem: console.log() not showing in Metro terminal

问题:iOS构建时出现Swift AppDelegate错误

Solution: Metro log forwarding removed in 0.77. Use React Native DevTools Console (press 'j') or
npx expo start --client-logs
(temporary workaround).
解决方案:在AppDelegate.swift中添加
RCTAppDependencyProvider.sharedInstance()
。请参阅Swift迁移部分。

Problem: Swift AppDelegate errors during iOS build

问题:Redux Store启动时崩溃

Solution: Add
RCTAppDependencyProvider.sharedInstance()
to AppDelegate.swift. See Swift migration section.
解决方案:用Redux Toolkit替代旧版
redux
+
redux-thunk
。安装
@reduxjs/toolkit

Problem: Redux store crashes on startup

问题:无法在0.82+中禁用New Architecture

Solution: Use Redux Toolkit instead of legacy
redux
+
redux-thunk
. Install
@reduxjs/toolkit
.
解决方案:0.82+中必须使用New Architecture。如果需要旧架构,请停留在0.81或更早版本(不推荐)。

Problem: Can't disable New Architecture in 0.82+

完整设置检查清单

Solution: New Architecture is mandatory in 0.82+. If you need legacy, stay on 0.81 or earlier (not recommended).

使用此清单验证您的设置:
  • 已安装React Native 0.76+或Expo SDK 52+
  • 已启用New Architecture(0.82+中自动启用)
  • 已启用Hermes引擎(默认)
  • 已完成React 19迁移(无propTypes、无forwardRef)
  • 已配置TypeScript进行类型检查
  • 可访问React Native DevTools(按'j')
  • 无深层导入(
    react-native/Libraries/*
  • 使用Redux Toolkit(而非旧版redux)
  • 使用react-i18next(而非i18n-js)
  • iOS构建成功(新项目使用Swift模板)
  • Android构建成功
  • 开发服务器无错误运行
  • 所有导航/状态管理功能正常

有疑问?遇到问题?
  1. 查看
    references/new-architecture-errors.md
    获取构建错误解决方案
  2. 查看
    references/react-19-migration.md
    获取React 19相关问题解决方案
  3. 查看官方文档:https://reactnative.dev/docs/new-architecture-intro
  4. 确保已启用New Architecture(0.82+中必须启用)
  5. 验证所有依赖项支持New Architecture

填补的知识空白:本指南涵盖了2024年12月后的React Native更新,这些是LLM可能不知道的内容。如果没有本指南,Claude可能会建议已弃用的API、已移除的功能和过时的模式。",

Complete Setup Checklist

Use this checklist to verify your setup:
  • React Native 0.76+ or Expo SDK 52+ installed
  • New Architecture enabled (automatic in 0.82+)
  • Hermes engine enabled (default)
  • React 19 migration complete (no propTypes, no forwardRef)
  • TypeScript configured for type checking
  • React Native DevTools accessible (press 'j')
  • No deep imports (
    react-native/Libraries/*
    )
  • Redux Toolkit (not legacy redux)
  • react-i18next (not i18n-js)
  • iOS builds successfully (Swift template if new project)
  • Android builds successfully
  • Dev server runs without errors
  • All navigation/state management working

Questions? Issues?
  1. Check
    references/new-architecture-errors.md
    for build errors
  2. Check
    references/react-19-migration.md
    for React 19 issues
  3. Check official docs: https://reactnative.dev/docs/new-architecture-intro
  4. Ensure New Architecture is enabled (mandatory in 0.82+)
  5. Verify all dependencies support New Architecture

Knowledge Gap Filled: This skill covers React Native updates from December 2024+ that LLMs won't know about. Without this skill, Claude would suggest deprecated APIs, removed features, and outdated patterns.