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: 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
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
---
**关键提示**:
- 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
undefinedSDK时间线:
- 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
undefinedThis 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 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) 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
undefinedJSC 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';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';🔴 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-contextSolution:
typescript
import { SafeAreaView } from 'react-native-safe-area-context';
function App() {
return (
<SafeAreaView style={{ flex: 1 }}>
{/* Content respects system bars */}
</SafeAreaView>
);
}Source: Expo SDK 54 Changelog
变更内容:
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
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可绘制资源(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 ? '提交中...' : '提交'}
</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/context)
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(pending时会暂停)
const user = use(userPromise);
return <Text>{user.name}</Text>;
}来源:React 19升级指南
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 16 documented issues:
本指南可避免16种已记录的问题:
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,运行移除propTypes
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发布说明
原因:0.77版本中移除了Metro日志转发
预防方法:使用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发布说明
原因:0.79版本中移除了旧Chrome调试器
预防方法:改用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应用崩溃,寻找名为的包
来源:CodePush GitHub Issues
原因:与New Architecture存在已知不兼容问题
预防方法:在New Architecture中避免使用CodePush,或等待官方支持
nullIssue #13: expo-file-system Legacy API Removed (SDK 55+)
问题#13:expo-file-system旧版API已移除(SDK 55+)
Error:
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
Module not found: expo-file-system/legacyMigration Timeline:
- SDK 53 and earlier: Legacy API at
expo-file-system - SDK 54: Legacy API at , new API at
expo-file-system/legacy(default)expo-file-system - 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);错误表现:
来源:Expo SDK 54更新日志, GitHub Issue #39056
原因:SDK 55中移除了旧版API,必须迁移至新的File/Directory类API
预防方法:升级到SDK 55前先迁移至新API
Module not found: expo-file-system/legacy迁移时间线:
- SDK 53及更早:旧版API位于
expo-file-system - SDK 54:旧版API位于,新版API位于
expo-file-system/legacy(默认)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:
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
Module not found: expo-avMigration Timeline:
- SDK 52: introduced
expo-video - SDK 53: introduced,
expo-audiodeprecatedexpo-av - SDK 54: Last release with (no patches)
expo-av - SDK 55: removed
expo-av
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')} />错误表现:
来源:Expo SDK 54更新日志, expo-av GitHub
原因:SDK 53中弃用该包,SDK 55中移除
预防方法:在SDK 55前迁移至expo-audio和expo-video
Module not found: expo-av迁移时间线:
- SDK 52:推出
expo-video - SDK 53:推出,弃用
expo-audioexpo-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 Version | Architecture Support | Expo SDK |
|---|---|---|
| v3 | Legacy + New Architecture | SDK 52-54 |
| v4 | New Architecture ONLY | SDK 54+ |
NativeWind Incompatibility:
bash
undefined错误表现:在旧架构下使用Reanimated v4会导致构建失败或崩溃
来源:Expo SDK 54 FYI
原因:Reanimated v4仅支持New Architecture
预防方法:在旧架构中使用Reanimated v3,或先迁移至New Architecture
版本矩阵:
| Reanimated版本 | 架构支持 | Expo SDK |
|---|---|---|
| v3 | 旧架构 + New Architecture | SDK 52-54 |
| v4 | 仅New Architecture | SDK 54+ |
NativeWind不兼容问题:
bash
// 截至2026年1月,NativeWind尚不支持Reanimated v4
// 如果使用NativeWind,必须保留Reanimated v3
npm install react-native-reanimated@^3迁移至v4(仅New Architecture支持):
- 安装(v4必需)
react-native-worklets - 遵循官方Reanimated v3 → v4迁移指南
- 如果使用,可跳过babel.config.js的修改(自动配置)
babel-preset-expo
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中显式设置标志
预防方法:在ios/Podfile中添加显式的Hermes标志
:hermes_enabled触发条件:
- Expo SDK 54
- 启用New Architecture
- 启用Hermes(默认)
- 使用
expo-updates - 仅iOS(Android不受影响)
解决方法:
ruby
undefinedIssue #16: iOS Crashes on Launch with Hermes + New Architecture (SDK 54) - Community-sourced
ios/Podfile
Error:
hermes::vm::JSObject::putComputed_RJS
hermes::vm::arrayPrototypePushSource: GitHub Issue #41824, Medium Post
Verified: Reproduction available
Why It Happens: Expo Updates requires explicit flag in Podfile when using New Architecture on iOS
Prevention: Add explicit Hermes flag to ios/Podfile
:hermes_enabledConditions:
- Expo SDK 54
- New Architecture enabled
- Hermes enabled (default)
- Using
expo-updates - iOS only (Android unaffected)
Workaround:
ruby
undefineduse_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
undefinedMigration 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
undefinednpx react-native --version
Check current version
先升级到0.81(最后一个支持互操作层的版本)
npx react-native --version
npm install react-native@0.81
npx expo install --fix
undefinedUpgrade to 0.81 first (last version with interop layer)
步骤2:启用New Architecture(如果尚未启用)
npm install react-native@0.81
npx expo install --fix
undefinedbash
undefinedStep 2: Enable New Architecture (if not already)
Android(gradle.properties)
bash
undefinednewArchEnabled=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
undefinedRebuild
步骤3:修复不兼容的依赖项
npm run ios
npm run android
undefined常见不兼容项:
bash
undefinedStep 3: Fix Incompatible Dependencies
用Redux Toolkit替代Redux
Common incompatibilities:
bash
undefinednpm 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
undefinedUpdate React Navigation (if old version)
步骤4:全面测试
npm install @react-navigation/native@latest
undefinedbash
undefinedStep 4: Test Thoroughly
在两个平台上运行
bash
undefinednpm run ios
npm run android
Run on both platforms
测试所有功能:
—
- 导航
—
- 状态管理(Redux)
—
- API调用
—
- 深度链接
—
- 推送通知
npm run ios
npm run android
undefinedTest all features:
步骤5:迁移至React 19(如果升级到0.78+)
- Navigation
—
- State management (Redux)
—
- API calls
—
- Deep linking
—
- Push notifications
—
undefinedbash
undefinedStep 5: Migrate to React 19 (if upgrading to 0.78+)
运行React 19代码修改工具
bash
undefinednpx @codemod/react-19 upgrade
Run React 19 codemod
手动验证:
—
- 移除所有propTypes声明
—
- 移除forwardRef包装器
—
- 更新到新Hook(useActionState、useOptimistic)
npx @codemod/react-19 upgrade
undefinedManually verify:
步骤6:升级到0.82+
- Remove all propTypes declarations
—
- Remove forwardRef wrappers
—
- Update to new hooks (useActionState, useOptimistic)
—
undefinedbash
undefinedStep 6: Upgrade to 0.82+
仅在New Architecture测试通过后执行!
bash
undefinednpm 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
undefinedRebuild
步骤7:将iOS迁移到Swift(如果是新项目)
npm run ios
npm run android
undefined新项目(0.77+)默认使用Swift。对于现有项目:
bash
undefinedStep 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
undefinedRCTAppDependencyProvider.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.shUsing 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.shundefinedOutput: ✅ React Native 0.82 - New Architecture mandatory
参考资料(references/)
Output: ⚠️ React Native 0.75 - Upgrade to 0.76+ recommended
—
undefinedreact-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
undefinedExpo 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
undefinednpx 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.0New 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- 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库ID:/facebook/react-native
Official Documentation
包版本(2026-01-21已验证)
- 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
构建工具要求(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+
Source: Expo SDK 54 Changelog
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 upgradeProblem: "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-logsProblem: 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 (temporary workaround).
npx expo start --client-logs解决方案:在AppDelegate.swift中添加。请参阅Swift迁移部分。
RCTAppDependencyProvider.sharedInstance()Problem: Swift AppDelegate errors during iOS build
问题:Redux Store启动时崩溃
Solution: Add to AppDelegate.swift. See Swift migration section.
RCTAppDependencyProvider.sharedInstance()解决方案:用Redux Toolkit替代旧版 + 。安装。
reduxredux-thunk@reduxjs/toolkitProblem: Redux store crashes on startup
问题:无法在0.82+中禁用New Architecture
Solution: Use Redux Toolkit instead of legacy + . Install .
reduxredux-thunk@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构建成功
- 开发服务器无错误运行
- 所有导航/状态管理功能正常
有疑问?遇到问题?
- 查看获取构建错误解决方案
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、已移除的功能和过时的模式。",
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.
—