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: 2025-11-22 Dependencies: Node.js 18+, Expo CLI Latest Versions: react-native@0.82, expo@~52.0.0, react@19.1

状态:可用于生产环境 最后更新:2025-11-22 依赖项:Node.js 18+、Expo CLI 最新版本:react-native@0.82, expo@~52.0.0, react@19.1

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

---

**关键注意事项**:
- 旧版Chrome调试器已在0.79版本中移除 - 请改用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+)

What Changed:
  • 0.76-0.81: New Architecture default, legacy frozen (no new features)
  • 0.82+: Legacy Architecture completely removed from codebase
Impact:
bash
undefined
变更内容
  • 0.76-0.81:New Architecture为默认选项,旧架构冻结(不再添加新功能)
  • 0.82+:旧架构已从代码库中完全移除
影响
bash
undefined

This will FAIL in 0.82+:

以下设置在0.82+版本中会失败:

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 first (if on 0.75 or earlier)
2. Test with New Architecture enabled
3. Fix incompatible dependencies (Redux, i18n, CodePush)
4. Then upgrade to 0.82+
RCT_NEW_ARCH_ENABLED=0 # ❌ 会被忽略,构建失败

**迁移路径**:
1. 若当前版本为0.75或更早,先升级到0.76-0.81版本
2. 启用New Architecture进行测试
3. 修复不兼容的依赖项(Redux、i18n、CodePush等)
4. 再升级到0.82+版本

🔴 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) moved out of React Native core, Hermes is default.
Before (0.78):
  • Both Hermes and JSC bundled
  • JSC available in Expo Go
After (0.79+):
json
// If you still need JSC (rare):
{
  "dependencies": {
    "@react-native-community/javascriptcore": "^1.0.0"
  }
}
Expo Go:
  • JSC completely removed from Expo Go (SDK 52+)
  • Hermes only
Note: JSC will eventually be removed entirely from React Native.
变更内容: JavaScriptCore(JSC)已从React Native核心代码中移出,Hermes成为默认引擎。
旧版本(0.78)
  • 同时捆绑Hermes和JSC
  • Expo Go中提供JSC
新版本(0.79+)
json
// 若仍需要JSC(罕见情况):
{
  "dependencies": {
    "@react-native-community/javascriptcore": "^1.0.0"
  }
}
Expo Go
  • Expo Go中已完全移除JSC(SDK 52+)
  • 仅支持Hermes
注意:JSC最终会从React Native中完全移除。

🔴 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';

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 Drawables(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 ? 'Submitting...' : 'Submit'}
      </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/上下文)

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(若未完成则暂停渲染)
  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 12 documented issues:
本内容可预防12个已记录的问题:

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
移除相关代码

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 发布说明 原因:Metro日志转发功能在0.77版本中被移除 解决方法:使用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 发布说明 原因:旧版Chrome调试器已在0.79版本中移除 解决方法:改用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
的bundle 来源CodePush GitHub Issues 原因:已知与New Architecture不兼容 解决方法:避免在New Architecture中使用CodePush,或等待官方支持

Migration Guide: 0.72-0.75 → 0.82+

迁移指南:0.72-0.75 → 0.82+

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

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

Why: Can't skip directly to 0.82 if using legacy architecture - you'll lose the interop layer.
bash
undefined
原因:若使用旧架构,无法直接跳过到0.82版本 - 会失去互操作层。
bash
undefined

Check current version

检查当前版本

npx react-native --version
npx react-native --version

Upgrade to 0.81 first (last version with interop layer)

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

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

Step 2: Enable New Architecture (if not already)

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

bash
undefined
bash
undefined

Android (gradle.properties)

Android(gradle.properties)

newArchEnabled=true
newArchEnabled=true

iOS

iOS

RCT_NEW_ARCH_ENABLED=1 bundle exec pod install
RCT_NEW_ARCH_ENABLED=1 bundle exec pod install

Rebuild

重新构建

npm run ios npm run android
undefined
npm run ios npm run android
undefined

Step 3: Fix Incompatible Dependencies

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

Common incompatibilities:
bash
undefined
常见不兼容项
bash
undefined

Replace Redux with Redux Toolkit

用Redux Toolkit替代Redux

npm uninstall redux redux-thunk npm install @reduxjs/toolkit react-redux
npm uninstall redux redux-thunk npm install @reduxjs/toolkit react-redux

Replace i18n-js with react-i18next

用react-i18next替代i18n-js

npm uninstall i18n-js npm install react-i18next i18next
npm uninstall i18n-js npm install react-i18next i18next

Update React Navigation (if old version)

更新React Navigation(若版本较旧)

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

Step 4: Test Thoroughly

步骤4:全面测试

bash
undefined
bash
undefined

Run on both platforms

在两个平台上运行

npm run ios npm run android
npm run ios npm run android

Test all features:

测试所有功能:

- Navigation

- 导航

- State management (Redux)

- 状态管理(Redux)

- API calls

- API调用

- Deep linking

- 深度链接

- Push notifications

- 推送通知

undefined
undefined

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

步骤5:迁移到React 19(若升级到0.78+)

bash
undefined
bash
undefined

Run React 19 codemod

运行React 19代码修改工具

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

Manually verify:

手动验证:

- Remove all propTypes declarations

- 移除所有propTypes声明

- Remove forwardRef wrappers

- 移除forwardRef包装

- Update to new hooks (useActionState, useOptimistic)

- 更新到新Hook(useActionState、useOptimistic)

undefined
undefined

Step 6: Upgrade to 0.82+

步骤6:升级到0.82+

bash
undefined
bash
undefined

Only after testing with New Architecture enabled!

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

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

Rebuild

重新构建

npm run ios npm run android
undefined
npm run ios npm run android
undefined

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

步骤7:将iOS项目迁移到Swift(若为新项目)

New projects (0.77+) use Swift by default. For existing projects:
bash
undefined
新项目(0.77+)默认使用Swift。对于现有项目:
bash
undefined

Follow upgrade helper

遵循升级助手指引

Select: 0.76 → 0.77

选择:0.76 → 0.77

CRITICAL: Add this line to AppDelegate.swift

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

RCTAppDependencyProvider.sharedInstance()

---
RCTAppDependencyProvider.sharedInstance()

---

Common Patterns

常见模式

Pattern 1: Conditional Rendering with New Hooks

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

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
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>
  );
}
适用场景:带加载/错误状态的表单提交

Pattern 2: TypeScript Instead of propTypes

模式2:用TypeScript替代propTypes

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
// 用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 3: New CSS for Visual Effects

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

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)

typescript
// 带轮廓和混合模式的发光按钮
function GlowButton({ title, onPress }) {
  return (
    <Pressable
      onPress={onPress}
      style={{
        backgroundColor: '#3b82f6',
        padding: 16,
        borderRadius: 8,
        // 轮廓不影响布局
        outlineWidth: 2,
        outlineColor: '#60a5fa',
        outlineOffset: 4,
        // 与背景混合
        mixBlendMode: 'screen',
        isolation: 'isolate'
      }}
    >
      <Text style={{ color: 'white', fontWeight: 'bold' }}>
        {title}
      </Text>
    </Pressable>
  );
}
适用场景:不影响布局的视觉效果(仅New Architecture支持)

Using Bundled Resources

使用捆绑资源

Scripts (scripts/)

脚本(scripts/)

check-rn-version.sh - Detects React Native version and warns about architecture requirements
Example Usage:
bash
./scripts/check-rn-version.sh
check-rn-version.sh - 检测React Native版本并警告架构要求
示例用法
bash
./scripts/check-rn-version.sh

Output: ✅ React Native 0.82 - New Architecture mandatory

输出:✅ React Native 0.82 - New Architecture强制启用

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

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

undefined
undefined

References (references/)

参考文档(references/)

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
react-19-migration.md - 详细的React 19破坏性变更和迁移步骤
new-architecture-errors.md - 启用New Architecture时常见的构建错误
expo-sdk-52-breaking.md - Expo SDK 52+特有的破坏性变更
Claude应何时加载这些文档:遇到迁移错误、构建失败或详细的React 19问题时

Assets (assets/)

资源(assets/)

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

new-arch-decision-tree.md - 选择React Native版本的决策树
css-features-cheatsheet.md - 新CSS属性的完整示例

Expo SDK 52+ Specifics

Expo SDK 52+ 专属内容

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
Expo Go中移除JSC
json
// 此配置在Expo Go(SDK 52+)中不再生效:
{
  "jsEngine": "jsc"  // ❌ 会被忽略,仅支持Hermes
}
Expo Go中移除Google Maps(SDK 53+)
bash
undefined

Must use custom dev client for Google Maps

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

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.
npx expo install expo-dev-client npx expo run:android

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

New Features (SDK 52)

新特性(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

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

Official Documentation

官方文档

Package Versions (Verified 2025-11-22)

包版本(2025-11-22已验证)

json
{
  "dependencies": {
    "react": "^19.1.0",
    "react-native": "^0.82.0",
    "expo": "~52.0.0",
    "@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"
  }
}

json
{
  "dependencies": {
    "react": "^19.1.0",
    "react-native": "^0.82.0",
    "expo": "~52.0.0",
    "@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"
  }
}

Troubleshooting

故障排除

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

问题:构建失败,提示「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).
解决方案:库不兼容New Architecture。查看库文档确认是否支持New Architecture,或使用互操作层(仅0.76-0.81版本支持)。

Problem: "propTypes is not a function" error

问题:出现「propTypes is not a function」错误

Solution: React 19 removed propTypes. Use TypeScript for type checking instead. Run
npx @codemod/react-19 upgrade
.
解决方案:React 19已移除propTypes。改用TypeScript进行类型检查。运行
npx @codemod/react-19 upgrade

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

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

Solution: Metro log forwarding removed in 0.77. Use React Native DevTools Console (press 'j') or
npx expo start --client-logs
(temporary workaround).
解决方案:Metro日志转发功能已在0.77版本中移除。使用React Native DevTools控制台(按'j')或
npx expo start --client-logs
(临时解决方法)。

Problem: Swift AppDelegate errors during iOS build

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

Solution: Add
RCTAppDependencyProvider.sharedInstance()
to AppDelegate.swift. See Swift migration section.
解决方案:在AppDelegate.swift中添加
RCTAppDependencyProvider.sharedInstance()
。请查看Swift迁移章节。

Problem: Redux store crashes on startup

问题:Redux Store在启动时崩溃

Solution: Use Redux Toolkit instead of legacy
redux
+
redux-thunk
. Install
@reduxjs/toolkit
.
解决方案:改用Redux Toolkit替代旧版
redux
+
redux-thunk
。安装
@reduxjs/toolkit

Problem: Can't disable New Architecture in 0.82+

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

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

解决方案:0.82+版本中New Architecture是强制启用的。若需要旧架构,请停留在0.81或更早版本(不推荐)。

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.
使用此清单验证你的设置:
  • 已安装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、已移除的功能和过时的模式。