react-native-expo
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseReact 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
undefinedbash
undefinedCreate 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
undefinedbash
undefinedCheck 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
undefinedbash
undefinedStart 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
undefinedThis 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 completely. No runtime validation, no warnings - silently ignored.
propTypesBefore (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
undefinedUse React 19 codemod to remove propTypes
使用React 19代码修改工具移除propTypes
npx @codemod/react-19 upgrade
undefinednpx @codemod/react-19 upgrade
undefined🔴 forwardRef Deprecated (React 19)
🔴 forwardRef已废弃(React 19)
What Changed:
no longer needed - pass as a regular prop.
forwardRefrefBefore (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} />;
}变更内容:
不再需要 - 直接将作为常规属性传递即可。
forwardRefref旧代码:
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 instead of Objective-C .
AppDelegate.swiftAppDelegate.mmOld Structure:
ios/MyApp/
├── main.m # ❌ Removed
├── AppDelegate.h # ❌ Removed
└── AppDelegate.mm # ❌ RemovedNew 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!Source: React Native 0.77 Release Notes
变更内容:
新项目默认使用Swift 替代Objective-C 。
AppDelegate.swiftAppDelegate.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 output.
console.log()Before (0.76):
bash
undefined变更内容:
Metro终端不再输出内容。
console.log()旧版本(0.76):
bash
undefinedconsole.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+)**:
```bashconsole.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 () removed. Use React Native DevTools instead.
chrome://inspectOld Method (Removed):
bash
undefined变更内容:
旧版Chrome调试器()已移除。请改用React Native DevTools。
chrome://inspect旧方法(已移除):
bash
undefined❌ This no longer works:
❌ 此方法不再有效:
Open Dev Menu → "Debug" → Chrome DevTools opens
打开开发菜单 → "Debug" → Chrome DevTools打开
**New Method (0.76+):**
```bash
**新方法(0.76+)**:
```bashPress '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';Source: React Native 0.80 Release Notes
变更内容:
从内部路径导入会导致代码崩溃。
旧代码:
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
display: contents1. display: contents
display: contentsMakes 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
boxSizing2. boxSizing
boxSizingControl 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
mixBlendModeisolation3. mixBlendMode
+ isolation
mixBlendModeisolationBlend 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: , , , , , , , , , , , , , ,
multiplyscreenoverlaydarkenlightencolor-dodgecolor-burnhard-lightsoft-lightdifferenceexclusionhuesaturationcolorluminosity像Photoshop一样混合图层:
typescript
<View style={{ backgroundColor: 'red' }}>
<View style={{
mixBlendMode: 'multiply', // 支持16种混合模式
backgroundColor: 'blue'
// 结果:紫色(红色 × 蓝色)
}} />
</View>
// 防止不必要的混合:
<View style={{ isolation: 'isolate' }}>
{/* 混合效果仅在该View内部生效 */}
</View>支持的模式:, , , , , , , , , , , , , ,
multiplyscreenoverlaydarkenlightencolor-dodgecolor-burnhard-lightsoft-lightdifferenceexclusionhuesaturationcolorluminosity4. outline
Properties
outline4. outline
属性
outlineVisual outline that doesn't affect layout (unlike ):
bordertypescript
<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.
Source: React Native 0.77 Release Notes
不影响布局的视觉轮廓(与不同):
bordertypescript
<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)
Source: React Native 0.78 Release Notes
将原生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)
useActionState1. useActionState
(替代表单模式)
useActionStatetypescript
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)
useOptimistic2. useOptimistic
(乐观UI更新)
useOptimistictypescript
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)
use3. use
(渲染时读取Promise/上下文)
usetypescript
import { use } from 'react';
function UserProfile({ userPromise }) {
// Read promise directly during render (suspends if pending)
const user = use(userPromise);
return <Text>{user.name}</Text>;
}Source: React 19 Upgrade Guide
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 in CLI
j - 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 - just doesn't work
Source: React 19 Upgrade Guide
Why It Happens: React 19 removed runtime propTypes validation
Prevention: Use TypeScript instead, run to remove
propTypesnpx @codemod/react-19 upgrade错误表现:无错误提示 - 完全不生效
来源:React 19 升级指南
原因:React 19移除了运行时propTypes验证
解决方法:改用TypeScript,运行移除相关代码
propTypesnpx @codemod/react-19 upgradeIssue #2: forwardRef Deprecated Warning
问题2:forwardRef废弃警告
Error:
Source: React 19 Upgrade Guide
Why It Happens: React 19 allows as a regular prop
Prevention: Remove wrapper, pass as prop directly
Warning: forwardRef is deprecatedrefforwardRefref错误表现:
来源:React 19 升级指南
原因:React 19允许将作为常规属性传递
解决方法:移除包装,直接将作为属性传递
Warning: forwardRef is deprecatedrefforwardRefrefIssue #3: New Architecture Cannot Be Disabled (0.82+)
问题3:0.82+版本中无法禁用New Architecture
Error: Build fails with
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
newArchEnabled=falseIssue #4: "Fabric component descriptor not found"
问题4:「Fabric component descriptor not found」
Error:
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版本支持)
Fabric component descriptor provider not found for componentIssue #5: "TurboModule not registered"
问题5:「TurboModule not registered」
Error:
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版本支持)
TurboModule '[ModuleName]' not foundIssue #6: Swift AppDelegate Missing RCTAppDependencyProvider
问题6:Swift AppDelegate缺失RCTAppDependencyProvider
Error:
Source: React Native 0.77 Release Notes
Why It Happens: When migrating from Objective-C to Swift template
Prevention: Add to AppDelegate.swift
RCTAppDependencyProvider not foundRCTAppDependencyProvider.sharedInstance()错误表现:
来源:React Native 0.77 发布说明
原因:从Objective-C模板迁移到Swift模板时
解决方法:在AppDelegate.swift中添加
RCTAppDependencyProvider not foundRCTAppDependencyProvider.sharedInstance()Issue #7: Metro Logs Not Appearing
问题7:Metro日志不显示
Error: 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 flag (temporary)
console.log()--client-logs错误表现:内容不显示在终端中
来源:React Native 0.77 发布说明
原因:Metro日志转发功能在0.77版本中被移除
解决方法:使用React Native DevTools控制台(按'j'),或使用标志(临时解决方法)
console.log()--client-logsIssue #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:
Source: React Native 0.80 Release Notes
Why It Happens: Internal paths deprecated, strict API enforced
Prevention: Import only from , not deep paths
Module not found: react-native/Libraries/...'react-native'错误表现:
来源:React Native 0.80 发布说明
原因:内部路径已废弃,API使用被严格限制
解决方法:仅从导入,不要使用深度路径
Module not found: react-native/Libraries/...'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 + incompatible with New Architecture
Prevention: Use Redux Toolkit () instead
reduxredux-thunk@reduxjs/toolkit错误表现:应用在创建Redux Store时崩溃
来源:Redux Toolkit 迁移指南
原因:旧版 + 与New Architecture不兼容
解决方法:改用Redux Toolkit()
reduxredux-thunk@reduxjs/toolkitIssue #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: not fully compatible with New Architecture
Prevention: Use instead
i18n-jsreact-i18next错误表现:翻译内容不更新,或应用崩溃
来源:社区反馈(GitHub issues)
原因:未完全兼容New Architecture
解决方法:改用
i18n-jsreact-i18nextIssue #12: CodePush Crashes on Android
问题12:CodePush在Android上崩溃
Error: Android crashes looking for bundle named
Source: CodePush GitHub Issues
Why It Happens: Known incompatibility with New Architecture
Prevention: Avoid CodePush with New Architecture, or wait for official support
null错误表现:Android应用崩溃,查找名为的bundle
来源:CodePush GitHub Issues
原因:已知与New Architecture不兼容
解决方法:避免在New Architecture中使用CodePush,或等待官方支持
nullMigration 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
undefinedCheck 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
undefinednpm install react-native@0.81
npx expo install --fix
undefinedStep 2: Enable New Architecture (if not already)
步骤2:启用New Architecture(若尚未启用)
bash
undefinedbash
undefinedAndroid (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
undefinednpm run ios
npm run android
undefinedStep 3: Fix Incompatible Dependencies
步骤3:修复不兼容的依赖项
Common incompatibilities:
bash
undefined常见不兼容项:
bash
undefinedReplace 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
undefinednpm install @react-navigation/native@latest
undefinedStep 4: Test Thoroughly
步骤4:全面测试
bash
undefinedbash
undefinedRun 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
- 推送通知
undefinedundefinedStep 5: Migrate to React 19 (if upgrading to 0.78+)
步骤5:迁移到React 19(若升级到0.78+)
bash
undefinedbash
undefinedRun 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)
undefinedundefinedStep 6: Upgrade to 0.82+
步骤6:升级到0.82+
bash
undefinedbash
undefinedOnly 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
undefinednpm run ios
npm run android
undefinedStep 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
undefinedFollow 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.shcheck-rn-version.sh - 检测React Native版本并警告架构要求
示例用法:
bash
./scripts/check-rn-version.shOutput: ✅ 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+
undefinedundefinedReferences (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
undefinedExpo Go中移除JSC:
json
// 此配置在Expo Go(SDK 52+)中不再生效:
{
"jsEngine": "jsc" // ❌ 会被忽略,仅支持Hermes
}Expo Go中移除Google Maps(SDK 53+):
bash
undefinedMust 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.0expo/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.0Official Documentation
官方文档
- React Native: https://reactnative.dev
- Expo: https://docs.expo.dev
- React 19: https://react.dev/blog/2024/04/25/react-19-upgrade-guide
- New Architecture: https://reactnative.dev/docs/new-architecture-intro
- Upgrade Helper: https://react-native-community.github.io/upgrade-helper/
- Context7 Library ID: /facebook/react-native
- React Native:https://reactnative.dev
- Expo:https://docs.expo.dev
- React 19:https://react.dev/blog/2024/04/25/react-19-upgrade-guide
- New Architecture:https://reactnative.dev/docs/new-architecture-intro
- 升级助手:https://react-native-community.github.io/upgrade-helper/
- Context7 Library ID:/facebook/react-native
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 upgradeProblem: 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 (temporary workaround).
npx expo start --client-logs解决方案:Metro日志转发功能已在0.77版本中移除。使用React Native DevTools控制台(按'j')或(临时解决方法)。
npx expo start --client-logsProblem: Swift AppDelegate errors during iOS build
问题:iOS构建时出现Swift AppDelegate错误
Solution: Add to AppDelegate.swift. See Swift migration section.
RCTAppDependencyProvider.sharedInstance()解决方案:在AppDelegate.swift中添加。请查看Swift迁移章节。
RCTAppDependencyProvider.sharedInstance()Problem: Redux store crashes on startup
问题:Redux Store在启动时崩溃
Solution: Use Redux Toolkit instead of legacy + . Install .
reduxredux-thunk@reduxjs/toolkit解决方案:改用Redux Toolkit替代旧版 + 。安装。
reduxredux-thunk@reduxjs/toolkitProblem: 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?
- Check for build errors
references/new-architecture-errors.md - Check for React 19 issues
references/react-19-migration.md - Check official docs: https://reactnative.dev/docs/new-architecture-intro
- Ensure New Architecture is enabled (mandatory in 0.82+)
- 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构建成功
- 开发服务器无错误运行
- 所有导航/状态管理功能正常
有疑问?遇到问题?
- 查看获取构建错误解决方案
references/new-architecture-errors.md - 查看获取React 19相关问题解决方案
references/react-19-migration.md - 查看官方文档:https://reactnative.dev/docs/new-architecture-intro
- 确保New Architecture已启用(0.82+版本强制要求)
- 验证所有依赖项支持New Architecture
填补的知识空白:本内容涵盖了2024年12月后的React Native更新,这些是LLM可能不知道的。如果没有本内容,Claude可能会建议已废弃的API、已移除的功能和过时的模式。