react-native-expo

React Native Expo（0.76-0.82+ / SDK 52+）

状态：已可用于生产环境 最后更新：2026-01-21 依赖项：Node.js 20.19.4+、Expo CLI、Xcode 16.1+（iOS） 最新版本：[email protected]、expo@~54.0.31、[email protected]

---

快速开始（15 分钟）

1. 创建新的 Expo 项目（RN 0.76+）

# Create new Expo app with React Native 0.76+
npx create-expo-app@latest my-app

cd my-app

# Install latest dependencies
npx expo install react-native@latest expo@latest

为什么这很重要：

• Expo SDK 52+ 使用默认启用新架构的 React Native 0.76+
• React Native 0.82+ 中必须使用新架构（无法禁用）
• Hermes 是唯一受支持的 JavaScript 引擎（Expo Go 已移除 JSC）

2. 验证新架构已启用

# Check if New Architecture is enabled (should be true by default)
npx expo config --type introspect | grep newArchEnabled

重要：

• React Native 0.82+ 要求使用新架构，旧架构已被彻底移除
• 如果从 0.75 或更早版本迁移，请先升级到 0.76-0.81，以使用互操作层
• 切勿尝试在 0.82+ 中禁用新架构（构建会失败）

3. 启动开发服务器

# Start Expo dev server
npx expo start

# Press 'i' for iOS simulator
# Press 'a' for Android emulator
# Press 'j' to open React Native DevTools (NOT Chrome debugger!)

重要：

• 0.79 已移除旧版 Chrome 调试器，请改用 React Native DevTools
• Metro 终端不再输出 console.log()，请使用 DevTools 控制台
• 键盘快捷键“a”/“i”可在 CLI 中使用，不能在 Metro 终端中使用

---

重大破坏性变更（2024 年 12 月起）

🔴 新架构成为必选项（0.82+）

SDK 时间线：

• Expo SDK 54（React Native 0.81）：最后一个支持旧架构的版本
• Expo SDK 55（React Native 0.83）：新架构成为必选项，旧架构被彻底移除

变更内容：

• 0.76-0.81 / SDK 52-54：默认使用新架构，旧架构被冻结（不再添加新功能）
• 0.82+ / SDK 55+：旧架构已从代码库中彻底移除

影响：

# This will FAIL in 0.82+ / SDK 55+:
# gradle.properties (Android)
newArchEnabled=false  # ❌ Ignored, build fails

# iOS
RCT_NEW_ARCH_ENABLED=0  # ❌ Ignored, build fails

迁移路径：

1. 如果使用 0.75 或更早版本，请先升级到 0.76-0.81 / SDK 54
2. 启用新架构进行测试
3. 修复不兼容的依赖项（Redux、i18n、CodePush、Reanimated v3 → v4）
4. 然后升级到 0.82+ / SDK 55+

来源：Expo SDK 54 更新日志

🔴 propTypes 已移除（React 19 / RN 0.78+）

变更内容： React 19 完全移除了 propTypes。不会进行运行时验证，也不会发出警告，而是直接忽略。

变更前（旧代码）：

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
};

变更后（使用 TypeScript）：

type MyComponentProps = {
  name: string;
  age?: number;
};

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

迁移：

# Use React 19 codemod to remove propTypes
npx @codemod/react-19 upgrade

🔴 forwardRef 已弃用（React 19）

变更内容： 不再需要 forwardRef，可将 ref 作为普通 prop 传递。

变更前（旧代码）：

import { forwardRef } from 'react';

const MyInput = forwardRef((props, ref) => {  // ❌ Deprecated
  return <TextInput ref={ref} {...props} />;
});

变更后（React 19）：

function MyInput({ ref, ...props }) {  // ✅ ref is a regular prop
  return <TextInput ref={ref} {...props} />;
}

🔴 Swift 成为 iOS 模板默认语言（0.77+）

变更内容： 新项目使用 Swift AppDelegate.swift，而不是 Objective-C AppDelegate.mm。

旧结构：

ios/MyApp/
├── main.m              # ❌ Removed
├── AppDelegate.h       # ❌ Removed
└── AppDelegate.mm      # ❌ Removed

新结构：

// ios/MyApp/AppDelegate.swift ✅
import UIKit
import React

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, ...) -> Bool {
    // App initialization
    return true
  }
}

迁移（0.76 → 0.77）： 升级现有项目时，必须添加此行：

// Add to AppDelegate.swift during migration
import React
import ReactCoreModules

RCTAppDependencyProvider.sharedInstance()  // ⚠️ CRITICAL: Must add this!

来源：React Native 0.77 发行说明

🔴 Metro 日志转发已移除（0.77+）

变更内容： Metro 终端不再输出 console.log() 内容。

变更前（0.76）：

# console.log() appeared in Metro terminal
$ npx expo start
> LOG  Hello from app!  # ✅ Appeared here

变更后（0.77+）：

# console.log() does NOT appear in Metro terminal
$ npx expo start
# (no logs shown)  # ❌ Removed

# Workaround (temporary, will be removed):
$ npx expo start --client-logs  # Shows logs, deprecated

解决方案： 改用 React Native DevTools 控制台（在 CLI 中按“j”）。

来源：React Native 0.77 发行说明

🔴 Chrome 调试器已移除（0.79+）

变更内容： 旧版 Chrome 调试器（chrome://inspect）已移除。请改用 React Native DevTools。

旧方法（已移除）：

# ❌ This no longer works:
# Open Dev Menu → "Debug" → Chrome DevTools opens

新方法（0.76+）：

# Press 'j' in CLI or Dev Menu → "Open React Native DevTools"
# ✅ Uses Chrome DevTools Protocol (CDP)
# ✅ Reliable breakpoints, watch values, stack inspection
# ✅ JS Console (replaces Metro logs)

限制：

• 暂不支持第三方扩展（Redux DevTools 等）
• 网络检查器计划于 0.83 中推出（2025 年底）

来源：React Native 0.79 发行说明

🔴 JSC 引擎移交社区维护（0.79+）

变更内容： React Native 0.81+ 核心已移除对 JavaScriptCore（JSC）的官方支持。该支持已移至社区软件包。

之前（0.78）：

• React Native 同时捆绑了 Hermes 和 JSC
• Expo Go 支持 JSC

之后（0.79+ / React Native 0.81+ / SDK 54）：

# JSC removed from React Native core
# If you still need JSC (rare):
npm install @react-native-community/javascriptcore

Expo Go：

• SDK 52+：Expo Go 已完全移除 JSC
• 仅支持 Hermes

注意： JSC 最终将从 React Native 中彻底移除。

来源： Expo SDK 54 Changelog

🔴 深层导入已弃用（0.80+）

变更内容： 从内部路径导入会导致程序无法运行。

之前（旧代码）：

// ❌ Deep imports deprecated
import Button from 'react-native/Libraries/Components/Button';
import Platform from 'react-native/Libraries/Utilities/Platform';

之后：

// ✅ Import only from 'react-native'
import { Button, Platform } from 'react-native';

来源： React Native 0.80 Release Notes

🔴 Android 强制启用 Edge-to-Edge（SDK 54+）

变更内容： SDK 54 中，所有 Android 应用默认启用 Edge-to-Edge 显示，且无法禁用。

影响：

// 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 影响： 内容现在会延伸到系统状态栏和导航栏下方。你必须使用 react-native-safe-area-context 手动处理内边距。

解决方案：

import { SafeAreaView } from 'react-native-safe-area-context';

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

来源： Expo SDK 54 Changelog

---

新功能（2024 年 12 月之后）

CSS 属性（仅限 0.77+ 新架构）

React Native 现在支持许多此前仅在 Web 上可用的 CSS 属性：

1. display: contents

让元素“不可见”，但保留其子元素在布局中：

<View style={{ display: 'contents' }}>
  {/* This View disappears, but Text still renders */}
  <Text>I'm still here!</Text>
</View>

适用场景： 不应影响布局的包装组件。

2. boxSizing

控制宽度和高度的计算方式：

// 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)
}} />

3. mixBlendMode + isolation

像在 Photoshop 中一样混合图层：

<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>

可用模式： multiply、screen、overlay、darken、lighten、color-dodge、color-burn、hard-light、soft-light、difference、exclusion、hue、saturation、color、luminosity

4. outline 属性

不会影响布局的视觉轮廓（与 border 不同）：

<View style={{
  outlineWidth: 2,
  outlineStyle: 'solid',      // solid | dashed | dotted
  outlineColor: 'blue',
  outlineOffset: 4,           // Space between element and outline
  outlineSpread: 2            // Expand outline beyond offset
}} />

主要区别： Outline 不会改变元素大小，也不会触发布局重新计算。

来源： React Native 0.77 Release Notes

Android XML Drawable（0.78+）

使用原生 Android 矢量 Drawable（XML）作为 Image 源：

// 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 }}
/>

优点：

• 可缩放矢量图形（与分辨率无关）
• 与 PNG 相比，APK 体积更小
• 在后台线程解码（性能更佳）

限制：

• 仅限构建时资源（不支持从网络加载）
• 仅限 Android（iOS 仍使用 SF Symbols 或 PNG）

来源： React Native 0.78 Release Notes

React 19 新增 Hook

1. useActionState（取代表单模式）

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>
  );
}

2. useOptimistic（乐观 UI 更新）

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>
  );
}

3. use（在渲染期间读取 Promise/Context）

import { use } from 'react';

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

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

来源： React 19 Upgrade Guide

React Native DevTools（0.76+）

访问方式：

• 在 CLI 中按 j
• 或打开 Dev Menu →“Open React Native DevTools”

功能：

• ✅ 断点可靠（不同于旧版 Chrome 调试器）
• ✅ 监视值、检查调用栈
• ✅ JS Console（取代 Metro 日志）
• ✅ 基于 Chrome DevTools Protocol（CDP）
• ⏳ 网络检查器（将在 0.83 中推出）
• ❌ 暂不支持第三方扩展

来源： React Native DevTools Announcement

---

预防已知问题

此技能可预防 16 个已记录的问题：

问题 #1：propTypes 被静默忽略

错误： 没有错误提示——propTypes 就是不起作用 来源： React 19 Upgrade Guide 原因： React 19 移除了运行时 propTypes 验证 预防方法： 改用 TypeScript，并运行 npx @codemod/react-19 upgrade 将其移除

问题 #2：forwardRef 已弃用警告

错误： Warning: forwardRef is deprecated 来源： React 19 升级指南 原因： React 19 允许将 ref 作为常规属性使用 预防： 移除 forwardRef 包装，直接将 ref 作为属性传递

问题 #3：无法禁用新架构（0.82+）

错误： 设置 newArchEnabled=false 时构建失败 来源： React Native 0.82 发布说明 原因： 旧架构已从代码库中彻底移除 预防： 升级到 0.82+ 之前，先迁移到新架构

问题 #4：“找不到 Fabric 组件描述符”

错误： Fabric component descriptor provider not found for component 来源： 新架构迁移指南 原因： 组件与新架构（Fabric）不兼容 预防： 将库更新到支持新架构的版本，或使用互操作层（0.76-0.81）

问题 #5：“未注册 TurboModule”

错误： TurboModule '[ModuleName]' not found 来源： 新架构迁移指南 原因： 原生模块需要支持新架构（TurboModules） 预防： 更新库以支持 TurboModules，或使用互操作层（0.76-0.81）

问题 #6：Swift AppDelegate 缺少 RCTAppDependencyProvider

错误： RCTAppDependencyProvider not found 来源： React Native 0.77 发布说明 原因： 从 Objective-C 迁移到 Swift 模板时会出现此问题 预防： 将 RCTAppDependencyProvider.sharedInstance() 添加到 AppDelegate.swift

问题 #7：Metro 日志未显示

错误： console.log() 未显示在终端中 来源： React Native 0.77 发布说明 原因： 0.77 中移除了 Metro 日志转发 预防： 使用 React Native DevTools Console（按 'j'），或使用 --client-logs 标志（临时方案）

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

错误： Chrome DevTools 无法连接 来源： React Native 0.79 发布说明 原因： 0.79 中移除了旧版 Chrome 调试器 预防： 改用 React Native DevTools（按 'j'）

问题 #9：深层导入错误

错误： Module not found: react-native/Libraries/... 来源： React Native 0.80 发布说明 原因： 内部路径已弃用，并强制执行严格 API 预防： 仅从 'react-native' 导入，不要使用深层路径

问题 #10：新架构下 Redux Store 崩溃

错误： 创建 Redux Store 时应用崩溃 来源： Redux Toolkit 迁移指南 原因： 旧版 redux + redux-thunk 与新架构不兼容 预防： 改用 Redux Toolkit（@reduxjs/toolkit）

问题 #11：i18n-js 在新架构下不稳定

错误： 翻译未更新，或应用崩溃 来源： 社区报告（GitHub 问题） 原因： i18n-js 尚未完全兼容新架构 预防： 改用 react-i18next

问题 #12：CodePush 在 Android 上崩溃

错误： Android 因查找名为 null 的包而崩溃 来源： CodePush GitHub 问题 原因： 已知与新架构不兼容 预防： 在新架构下避免使用 CodePush，或等待官方支持

问题 #13：expo-file-system Legacy API 已移除（SDK 55+）

错误： Module not found: expo-file-system/legacy 来源： Expo SDK 54 更新日志、GitHub Issue #39056 发生原因： SDK 55 中移除了 Legacy API，必须迁移到新的 File/Directory 类 API 预防措施： 在升级到 SDK 55 之前迁移到新 API

迁移时间线：

• SDK 53 及更早版本：Legacy API 位于 expo-file-system
• SDK 54：Legacy API 位于 expo-file-system/legacy，新 API 位于 expo-file-system（默认）
• SDK 55：Legacy API 被完全移除

旧代码（SDK 54，使用 legacy 导入）：

import * as FileSystem from 'expo-file-system/legacy';
await FileSystem.writeAsStringAsync(uri, content);

新代码（SDK 54+，使用新 API）：

import { File } from 'expo-file-system';
const file = new File(uri);
await file.writeString(content);

问题 #14：expo-av 已移除（SDK 55+）

错误： Module not found: expo-av 来源： Expo SDK 54 更新日志、expo-av GitHub 发生原因： 此软件包在 SDK 53 中弃用，在 SDK 55 中移除 预防措施： 在 SDK 55 之前迁移到 expo-audio 和 expo-video

迁移时间线：

• SDK 52：引入 expo-video
• SDK 53：引入 expo-audio，弃用 expo-av
• SDK 54：expo-av 的最后一个版本（不再提供补丁）
• SDK 55：移除 expo-av

迁移 - 音频：

// 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();

迁移 - 视频：

// 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')} />

问题 #15：Reanimated v4 需要新架构

错误： 在旧架构上使用 Reanimated v4 时，构建失败或发生崩溃 来源： Expo SDK 54 说明 发生原因： Reanimated v4 只能使用新架构 预防措施： 在旧架构上使用 Reanimated v3，或先迁移到新架构

版本对应关系：

Reanimated 版本	架构支持	Expo SDK
v3	旧架构 + 新架构	SDK 52-54
v4	仅支持新架构	SDK 54+

与 NativeWind 不兼容：

# NativeWind does not support Reanimated v4 yet (as of Jan 2026)
# If using NativeWind, must stay on Reanimated v3
npm install react-native-reanimated@^3

迁移到 v4（仅限新架构）：

1. 安装 react-native-worklets（v4 必需）
2. 按照官方 Reanimated v3 → v4 迁移指南操作
3. 如果使用 babel-preset-expo，可跳过 babel.config.js 的修改（会自动配置）

问题 #16：启用 Hermes + 新架构时 iOS 启动崩溃（SDK 54）- 来自社区

错误：

hermes::vm::JSObject::putComputed_RJS
hermes::vm::arrayPrototypePush

来源： GitHub Issue #41824、Medium 文章 已验证： 提供了复现方法 发生原因： 在 iOS 上使用新架构时，Expo Updates 要求在 Podfile 中显式设置 :hermes_enabled 标记 预防措施： 在 ios/Podfile 中显式添加 Hermes 标记

适用条件：

• Expo SDK 54
• 已启用新架构
• 已启用 Hermes（默认）
• 使用 expo-updates
• 仅限 iOS（Android 不受影响）

解决方法：

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

注意： 这是来自社区的发现，附有复现仓库，尚未在 Expo 更新日志中正式记录。

---

迁移指南：0.72-0.75 → 0.82+

步骤 1：先升级到互操作层（0.76-0.81）

原因： 如果使用旧架构，就不能直接跳到 0.82，否则会失去互操作层。

# Check current version
npx react-native --version

# Upgrade to 0.81 first (last version with interop layer)
npm install [email protected]
npx expo install --fix

步骤 2：启用新架构（如果尚未启用）

# Android (gradle.properties)
newArchEnabled=true

# iOS
RCT_NEW_ARCH_ENABLED=1 bundle exec pod install

# Rebuild
npm run ios
npm run android

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

常见的不兼容情况：

# Replace Redux with Redux Toolkit
npm uninstall redux redux-thunk
npm install @reduxjs/toolkit react-redux

# Replace i18n-js with react-i18next
npm uninstall i18n-js
npm install react-i18next i18next

# Update React Navigation (if old version)
npm install @react-navigation/native@latest

步骤 4：彻底测试

# Run on both platforms
npm run ios
npm run android

# Test all features:
# - Navigation
# - State management (Redux)
# - API calls
# - Deep linking
# - Push notifications

步骤 5：迁移到 React 19（如果升级到 0.78+）

# Run React 19 codemod
npx @codemod/react-19 upgrade

# Manually verify:
# - Remove all propTypes declarations
# - Remove forwardRef wrappers
# - Update to new hooks (useActionState, useOptimistic)

步骤 6：升级到 0.82+

# Only after testing with New Architecture enabled!
npm install [email protected]
npx expo install --fix

# Rebuild
npm run ios
npm run android

步骤 7：将 iOS 迁移到 Swift（如果是新项目）

新项目（0.77+）默认使用 Swift。对于现有项目：

# Follow upgrade helper
# https://react-native-community.github.io/upgrade-helper/
# Select: 0.76 → 0.77

# CRITICAL: Add this line to AppDelegate.swift
RCTAppDependencyProvider.sharedInstance()

---

常见模式

模式 1：使用新 Hooks 的条件渲染

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>
  );
}

适用场景： 带有加载/错误状态的表单提交

模式 2：使用 TypeScript 替代 propTypes

// 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>
  );
}

适用情况： 始终使用（React 19 已移除 propTypes）

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

// 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>
  );
}

适用情况： 实现不影响布局的视觉效果（仅限新架构）

---

使用捆绑资源

脚本（scripts/）

check-rn-version.sh - 检测 React Native 版本，并提醒架构要求

使用示例：

./scripts/check-rn-version.sh
# Output: ✅ React Native 0.82 - New Architecture mandatory
# Output: ⚠️ React Native 0.75 - Upgrade to 0.76+ recommended

参考文档（references/）

react-19-migration.md - React 19 重大变更和迁移步骤详解

new-architecture-errors.md - 启用新架构时的常见构建错误

expo-sdk-52-breaking.md - Expo SDK 52+ 的特定重大变更

Claude 应在以下情况下加载这些文档： 遇到迁移错误、构建失败或 React 19 相关的详细问题时

资源文件（assets/）

new-arch-decision-tree.md - 选择 React Native 版本的决策树

css-features-cheatsheet.md - 新 CSS 属性的完整示例

---

Expo SDK 52+ 特有内容

重大变更

Expo Go 已移除 JSC：

// This no longer works in Expo Go (SDK 52+):
{
  "jsEngine": "jsc"  // ❌ Ignored, Hermes only
}

Expo Go 已移除 Google Maps（SDK 53+）：

# Must use custom dev client for Google Maps
npx expo install expo-dev-client
npx expo run:android

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

新功能（SDK 52）

expo/fetch（符合 WinterCG 标准）：

import { fetch } from 'expo/fetch';

// Standards-compliant fetch for Workers/Edge runtimes
const response = await fetch('https://api.example.com/data');

React Navigation v7：

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
• 新架构：https://reactnative.dev/docs/new-architecture-intro
• 升级辅助工具：https://react-native-community.github.io/upgrade-helper/
• Context7 库 ID：/facebook/react-native

---

软件包版本（已于 2026-01-21 验证）

构建工具要求（SDK 54+）：

• Xcode：最低 16.1，推荐使用 Xcode 16
• Node.js：最低 20.19.4
• iOS 部署目标：iOS 15.1+

来源： Expo SDK 54 更新日志

{
  "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"
  }
}

---

故障排除

问题：构建失败，提示“Fabric component descriptor not found”

解决方案： 该库与新架构不兼容。请查看库文档，确认其是否支持新架构，或使用互操作层（仅限 0.76-0.81）。

问题：报错“propTypes is not a function”

解决方案： React 19 已移除 propTypes。请改用 TypeScript 进行类型检查。运行 npx @codemod/react-19 upgrade。

问题：Metro 终端中没有显示 console.log()

解决方案： Metro 日志转发已在 0.77 中移除。请使用 React Native DevTools Console（按 'j'），或运行 npx expo start --client-logs（临时解决方法）。

问题：iOS 构建期间出现 Swift AppDelegate 错误

解决方案： 将 RCTAppDependencyProvider.sharedInstance() 添加到 AppDelegate.swift。请参阅 Swift 迁移部分。

问题：Redux store 启动时崩溃

解决方案： 请使用 Redux Toolkit 替代旧版 redux + redux-thunk。安装 @reduxjs/toolkit。

问题：无法在 0.82+ 中禁用新架构

解决方案： 新架构在 0.82+ 中为强制启用。如果需要使用旧架构，请停留在 0.81 或更早版本（不推荐）。

---

完整设置检查清单

使用此检查清单验证你的设置：

• 已安装 React Native 0.76+ 或 Expo SDK 52+
• 已启用新架构（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. 确认已启用新架构（0.82+ 中必须启用）
5. 确认所有依赖项都支持新架构

---

填补的知识盲区： 此技能涵盖了 2024 年 12 月及之后的 React Native 更新，这些内容是大模型不了解的。如果没有此技能，Claude 会建议使用已弃用的 API、已移除的功能和过时的模式。