# React Native Expo（0.76-0.82+ / SDK 52+） **状态**：生产就绪 **最后更新**：2025-11-22 **依赖项**：Node.js 18+、Expo CLI **最新版本**：react-native@0.82、expo@~52.0.0、react@19.1 ** ** ## 快速入门（15 分钟） ### 1\.创建新的世博项目（RN 0.76+） # 使用 React Native 0.76+ 创建新的 Expo 应用程序 npx create-expo-app@latest my-app cd 我的应用程序 # 安装最新的依赖项 npx expo 安装react-native@latest expo@latest **为什么这很重要：** * Expo SDK 52+ 使用 React Native 0.76+，默认启用新架构 * 新架构在 React Native 0.82+ 中是**强制**（无法禁用） * Hermes 是唯一受支持的 JavaScript 引擎（JSC 从 Expo Go 中删除） ### 2\.验证新架构已启用 # 检查是否启用了新架构（默认情况下应为 true） npx expo config --类型 introspect | grep newArchEnabled **关键：** * React Native 0.82+ **需要**新架构 - 遗留架构完全删除 * 如果从 0.75 或更早版本迁移，请先升级到 0.76-0.81 以使用互操作层 * 切勿尝试在 0.82+ 中禁用新架构（构建将会失败） ### 3\.启动开发服务器 # 启动 Expo 开发服务器 npx展会开始 # 按“i”进入 iOS 模拟器 # 按“a”键进入 Android 模拟器 # 按“j”打开 React Native DevTools（不是 Chrome 调试器！） **关键：** * 0.79 中删除了旧的 Chrome 调试器 - 使用 React Native DevTools 代替 * Metro 终端不再传输 `console.log()` \ - 使用 DevTools Console * 键盘快捷键“a”/“i”适用于 CLI，不适用于 Metro 终端 ** ** ## 重大重大变更（2024 年 12 月以上） ### 🔴新架构强制（0.82+） **改变了什么：** * **0.76-0.81** ：新架构默认值，旧版冻结（无新功能） * **0.82+**：遗留架构**从代码库中完全删除** **影响：** # 这将在 0.82+ 中失败： # gradle.properties (Android) newArchEnabled=false # ❌ 忽略，构建失败 # iOS RCT_NEW_ARCH_ENABLED=0 # ❌ 忽略，构建失败 **迁移路径：** 1. 首先升级到0.76-0.81（如果是0.75或更早版本） 2.启用新架构的测试 3.修复不兼容的依赖项（Redux、i18n、CodePush） 4.然后升级到0.82+ ### 🔴 propTypes 已删除（React 19 / RN 0.78+） **更改内容：** React 19 完全删除了 `propTypes`。没有运行时验证，没有警告 - 默默地忽略。 **之前（旧代码）：** 从“prop-types”导入 PropTypes；函数 MyComponent({ 姓名, 年龄 }) { return {name} 是 {age}; } MyComponent.propTypes = { // ❌ 在 React 19 中被默默忽略名称：PropTypes.string.isRequired，年龄：PropTypes.number }; **之后（使用 TypeScript）：** 类型 MyComponentProps = { 名称：字符串；年龄？：数字； }; 函数 MyComponent({ 姓名, 年龄 }: MyComponentProps) { return {name} 是 {age}; } **迁移：** # 使用 React 19 codemod 删除 propTypes npx @codemod/react-19 升级 ### 🔴forwardRef 已弃用（React 19） **更改内容：** 不再需要 `forwardRef` - 将 `ref` 作为常规 prop 传递。 **之前（旧代码）：** 从'react'导入{forwardRef}； const MyInput =forwardRef((props, ref) => { // ❌ 已弃用返回 ; }); **之后（反应 19）：** function MyInput({ ref, ...props }) { // ✅ ref 是常规 prop 返回 ; } ### 🔴 Swift iOS 模板默认（0.77+） **更改内容：** 新项目使用 Swift `AppDelegate.swift` 而不是 Objective-C `AppDelegate.mm`。 **旧结构：** ios/我的应用程序/ ├── main.m # ❌ 已移除 ├── AppDelegate.h # ❌ 已移除 └── AppDelegate.mm # ❌ 已移除 **新结构：** // ios/MyApp/AppDelegate.swift ✅ 导入 UIKit 导入反应 @主要类AppDelegate：UIResponder，UIApplicationDelegate { func application(_ application: UIApplication, ...) -> Bool { // 应用程序初始化返回真 } } **迁移（0.76→0.77）：**升级现有项目时，您**必须**添加此行： // 在迁移过程中添加到 AppDelegate.swift 导入反应导入 ReactCoreModules RCTAppDependencyProvider.sharedInstance() // ⚠️ 关键：必须添加这个！ **来源：** [React Native 0.77 发行说明]() ### 🔴 Metro 日志转发已删除（0.77+） **更改内容：** Metro 终端不再传输 `console.log()` 输出。 **之前 (0.76)：** # console.log()出现在地铁站 $ npx 博览会开始 > 来自应用程序的日志你好！ # ✅ 出现在这里 **（0.77+）之后：** # console.log() 不会出现在地铁终点站 $ npx 博览会开始 #（未显示日志）# ❌已删除 # 解决方法（临时的，将被删除）： $ npx expo start --client-logs # 显示日志，已弃用 **解决方案：** 使用 React Native DevTools Console（在 CLI 中按“j”）。 **来源：** [React Native 0.77 发行说明]() ### 🔴 Chrome 调试器已删除（0.79+） **更改内容：** 旧版 Chrome 调试器 (`chrome://inspect`) 已删除。请改用 React Native DevTools。 **旧方法（已删除）：** # ❌ 这不再有效： # 打开开发菜单→“调试”→ Chrome DevTools 打开 **新方法（0.76+）：** # 在 CLI 或开发菜单中按“j”→“打开 React Native DevTools” # ✅ 使用 Chrome 开发者工具协议 (CDP) # ✅ 可靠的断点、监视值、堆栈检查 # ✅ JS 控制台（替换 Metro 日志） **限制：** * 尚不支持第三方扩展（Redux DevTools 等） * 网络检查员将于 0.83 版本中推出（2025 年末） **来源：** [React Native 0.79 发行说明]() ### 🔴 JSC 引擎移至社区（0.79+） **更改内容：** JavaScriptCore (JSC) 移出了 React Native 核心，Hermes 是默认值。 **之前 (0.78)：** * Hermes 和 JSC 捆绑销售 * JSC 在 Expo Go 中可用 **（0.79+）之后：** // 如果您仍然需要 JSC（罕见）： { “依赖项”：{ “@react-native-community/javascriptcore”：“^1.0.0” } } **世博会：** * JSC 从 Expo Go 中完全删除（SDK 52+） * 仅限爱马仕 **注意：** JSC 最终将从 React Native 中完全删除。 ### 🔴 深度导入已弃用 (0.80+) **更改内容：** 从内部路径导入将会中断。 **之前（旧代码）：** // ❌ 已弃用深度导入从“react-native/Libraries/Components/Button”导入按钮；从“react-native/Libraries/Utilities/Platform”导入平台； **之后：** // ✅ 仅从 'react-native' 导入从'react-native'导入{按钮，平台}； **来源：** [React Native 0.80 发行说明]() ** ** ## 新功能（2024 年 12 月后） ### CSS 属性（仅限 0.77+ 新架构） React Native 现在支持许多以前仅在 Web 上可用的 CSS 属性： #### 1\. `显示：内容` 使元素“不可见”，但将其子元素保留在布局中： <视图样式={{显示：'内容'}}> {/* 该视图消失，但文本仍然呈现 */} 我还在这里！ **用例：** 不应该影响布局的包装组件。 #### 2\. `盒子大小` 控制宽度/高度的计算方式： // 默认：盒子内的填充/边框 <视图样式={{ boxSizing: 'border-box', // 默认宽度：100，填充：10，边框宽度：2 // 总宽度：100（内边距/边框） }} /> // 内容框：外边距/边框 <视图样式={{ boxSizing: '内容框', 宽度：100，填充：10，边框宽度：2 // 总宽度：124（100 + 20 内边距 + 4 边框） }} /> #### 3\. `mixBlendMode` \+ `隔离` 像 Photoshop 一样混合图层： <视图样式={{backgroundColor: 'red' }}> <视图样式={{ mixBlendMode: 'multiply', // 16 种可用模式背景颜色：'蓝色' // 结果：紫色（红×蓝） }} /> // 防止不必要的混合： <视图样式={{隔离：'隔离'}}> {/* 此视图中包含的混合 */} **可用模式：** `正片叠底`、`屏幕`、`叠加`、`变暗`、`变亮`、`颜色减淡`、`颜色加深`、`硬光`、`柔光`、`差异`、`排除`、`色调`、`饱和度`、`颜色`、`亮度` #### 4\. `outline` 属性不影响布局的视觉轮廓（与“border”不同）： <视图样式={{ 轮廓宽度：2，轮廓样式: 'solid', // 实心 |虚线|点缀的轮廓颜色：'蓝色'， outlineOffset: 4, // 元素和轮廓之间的空间 outlineSpread: 2 // 扩展轮廓超出偏移量 }} /> **主要区别：** Outline 不会更改元素大小或触发布局重新计算。 **来源：** [React Native 0.77 发行说明]() ### Android XML 绘图 (0.78+) 使用原生 Android 矢量绘图 (XML) 作为图像源： // 在构建时加载 XML 可绘制对象从 './assets/my_icon.xml' 导入 MyIcon； <图片来源={我的图标} 样式={{宽度：40，高度：40}} /> // 或者使用 require: <图片源={require('./assets/my_icon.xml')} 样式={{宽度：40，高度：40}} /> **好处：** * 可缩放矢量图形（与分辨率无关） * 与 PNG 相比，APK 尺寸更小 * 离线解码（更好的性能） **限制：** * 仅构建时资源（无网络加载） * 仅限 Android（iOS 仍使用 SF 符号或 PNG） **来源：** [React Native 0.78 发行说明]() ### React 19 个新 Hook #### 1\. `useActionState`（替换表单模式）从'react'导入{useActionState}；函数 MyForm() { const [状态，submitAction，isPending] = useActionState( 异步（prevState，formData）=> { // 异步表单提交 const 结果 = 等待 api.submit(formData); 返回结果； }, { message: '' } // 初始状态）；返回（ <表单操作={submitAction}> <按钮已禁用={isPending}> {正在等待？ '正在提交...' : '提交'} {state.message && {state.message}} ）； } #### 2\. `useOptimistic`（乐观的 UI 更新）从 'react' 导入 { useOptimistic } ；函数LikeButton（{ postId，initialLikes }）{ const [optimisticLikes, addOptimisticLike] = useOptimistic( 最初的喜欢， (当前点赞数, 数量) => 当前点赞数 + 数量）；异步函数handleLike() { 添加乐观喜欢（1）； // 立即更新UI 等待 api.like(postId); // 然后更新服务器 } 返回（ <按钮onPress={handleLike}> ❤️ {乐观的喜欢} ）； } #### 3\. `use` （在渲染期间读取承诺/上下文）从“反应”导入{使用}；函数 UserProfile({ userPromise }) { // 在渲染期间直接读取 Promise（如果挂起则暂停） const 用户 = use(userPromise); return {用户名}; } **来源：** [React 19 升级指南]() ### React Native 开发工具 (0.76+) **访问：** * 在 CLI 中按 `j` * 或者打开开发菜单→“打开React Native DevTools” **特点：** * ✅ 可靠的断点（与旧的 Chrome 调试器不同） * ✅ 观察值、调用堆栈检查 * ✅ JS 控制台（替换 Metro 日志） * ✅ 基于 Chrome DevTools 协议 (CDP) * ⏳ 网络检查器（0.83 版本中推出） * ❌ 尚不支持第三方扩展 **来源：** [React Native DevTools 公告]() ** ** ## 已知问题预防此技能可防止 **12** 已记录的问题： ### 问题#1：propTypes 被默默忽略 **错误：**没有错误 - `propTypes` 不起作用 **来源：** [React 19 升级指南]() **发生原因：** React 19 删除了运行时 propTypes 验证 **预防：** 使用 TypeScript 代替，运行 `npx @codemod/react-19 update` 来删除 ### 问题 #2：forwardRef 已弃用警告 **错误：** `警告：forwardRef 已被弃用` **来源：** [React 19 升级指南]() **发生原因：** React 19 允许 `ref` 作为常规 prop **预防：** 删除 `forwardRef` 包装器，直接将 `ref` 作为 prop 传递 ### 问题#3：无法禁用新架构（0.82+） **错误：** 构建因 `newArchEnabled=false` 失败 **来源：** [React Native 0.82 发行说明]() **发生原因：** 旧架构已从代码库中完全删除 **预防措施：** 在升级到 0.82+ 之前迁移到新架构 ### 问题#4：“未找到结构组件描述符” **错误：** `Fabric 组件描述符提供程序未找到组件` **来源：** [新架构迁移指南]() **发生原因：** 组件与新架构 (Fabric) 不兼容 **预防：** 将库更新到新架构版本，或使用互操作层 (0.76-0.81) ### 问题#5：“TurboModule 未注册” **错误：** `TurboModule '[ModuleName]' 未找到` **来源：** [新架构迁移指南]() **发生原因：** 本机模块需要新架构支持 (TurboModules) **预防：** 更新库以支持 TurboModules，或使用互操作层 (0.76-0.81) ### 问题 #6：Swift AppDelegate 缺少 RCTAppDependencyProvider **错误：** `RCTAppDependencyProvider not found` **来源：** [React Native 0.77 Release Notes]() **发生原因：**从 Objective-C 迁移到 Swift 模板时 **预防：** 将 `RCTAppDependencyProvider.sharedInstance()` 添加到 AppDelegate.swift ### 问题 #7：Metro 日志未出现 **错误：** `console.log()` 不在终端中显示 **来源：** [React Native 0.77 发行说明]() **发生原因：** Metro 日志转发在 0.77 中删除 **预防：** 使用 React Native DevTools Console（按 'j'）或 `--client-logs` 标志（临时） ### 问题#8：Chrome 调试器不工作 **错误：** Chrome DevTools 无法连接 **来源：** [React Native 0.79 发行说明]() **发生原因：** 0.79 中删除了旧的 Chrome 调试器 **预防措施：** 使用 React Native DevTools（按“j”） ### 问题 #9：深度导入错误 **错误：** `找不到模块：react-native/Libraries/...` **来源：** [React Native 0.80 发行说明]() **发生原因：** 内部路径已弃用，严格执行 API **预防措施：** 仅从 `'react-native'` 导入，而不是深层路径 ### 问题 #10：Redux Store 在新架构下崩溃 **错误：**应用程序在创建 Redux 存储时崩溃 **来源：** [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，或等待官方支持 ** ** ## 迁移指南：0.72-0.75 → 0.82+ ### 步骤 1：首先升级到互操作层 (0.76-0.81) **原因：** 如果使用旧架构，则无法直接跳至 0.82 - 您将失去互操作层。 # 检查当前版本 npx 反应本机--版本 # 首先升级到0.81（带有互操作层的最后一个版本） npm 安装react-native@0.81 npx expo 安装 --fix ### 第 2 步：启用新架构（如果尚未启用） # Android (gradle.properties) newArchEnabled=true # iOS RCT_NEW_ARCH_ENABLED=1 捆绑执行 pod 安装 # 重建 npm 运行 ios npm 运行 Android ### 步骤 3：修复不兼容的依赖关系 **常见的不兼容性：** # 将 Redux 替换为 Redux 工具包 npm 卸载 redux redux-thunk npm install @reduxjs/工具包react-redux # 用react-i18next替换i18n-js npm 卸载 i18n-js npm 安装react-i18next i18next # 更新 React Navigation（如果是旧版本） npm install @react-navigation/native@latest ### 第 4 步：彻底测试 # 在两个平台上运行 npm 运行 ios npm 运行 Android # 测试所有功能： # - 导航 # - 状态管理（Redux） # - API 调用 # - 深层链接 # - 推送通知 ### 步骤 5：迁移到 React 19（如果升级到 0.78+） # 运行 React 19 codemod npx @codemod/react-19 升级 # 手动验证： # - 删除所有 propTypes 声明 # - 删除forwardRef包装器 # - 更新到新的钩子（useActionState、useOptimistic） ### 第 6 步：升级到 0.82+ # 仅在启用新架构的情况下进行测试后！ npm 安装react-native@0.82 npx expo 安装 --fix # 重建 npm 运行 ios npm 运行 Android ### 第 7 步：将 iOS 迁移到 Swift（如果是新项目）新项目（0.77+）默认使用 Swift。对于现有项目： # 关注升级助手 # https://react-native-community.github.io/upgrade-helper/ # 选择：0.76 → 0.77 # 关键：将此行添加到 AppDelegate.swift RCTAppDependencyProvider.sharedInstance() ** ** ## 常见模式 ### 模式 1：使用新 Hooks 进行条件渲染从'react'导入{useActionState}；函数登录表单（）{ const [状态，loginAction，isPending] = useActionState( 异步（prevState，formData）=> { 尝试{ const user = wait api.login(formData); 返回{成功：true，用户}； } 捕获（错误）{ 返回 { 成功: false, 错误: error.message }; } }, { 成功：假 } ）；返回（ <查看> <表单操作={loginAction}> <按钮已禁用={isPending}> {正在等待？ '正在登录...' : '登录'} {!state.success && state.error && ( {state.error} )} ）； } **何时使用：** 带有加载/错误状态的表单提交 ### 模式 2：TypeScript 而不是 propTypes // 使用 TypeScript 定义 prop 类型类型 ButtonProps = { 标题：字符串； onPress: () => void; 禁用？：布尔值；变体？： '主要' | “次要”； }; 函数按钮（{标题，onPress，禁用= false，变体='主要'}：ButtonProps）{ 返回（ <可按压 onPress={onPress} 禁用={禁用} style={[styles.button, styles[variant]]} > <文本样式={styles.text}>{标题} ）； } **何时使用：** 始终（React 19 中删除了 propTypes） ### 模式 3：用于视觉效果的新 CSS // 具有轮廓和混合模式的发光按钮函数 GlowButton({ 标题, onPress }) { 返回（ <可按压 onPress={onPress} 风格={{ 背景颜色: '#3b82f6', 填充：16，边框半径：8， // 轮廓不影响布局轮廓宽度：2，轮廓颜色: '#60a5fa', 轮廓偏移：4， // 与背景混合 mixBlendMode: '屏幕', 隔离：“隔离” }} > <文字样式={{ color: 'white', fontWeight: 'bold' }}> {标题} ）； } **何时使用：** 不影响布局的视觉效果（仅限新架构） ** ** ## 使用捆绑资源 ### 脚本（脚本/） **check-rn-version.sh** \- 检测 React Native 版本并警告架构要求 **用法示例：** ./scripts/check-rn-version.sh # 输出： ✅ React Native 0.82 - 强制新架构 # 输出：⚠️ React Native 0.75 - 建议升级到 0.76+ ### 参考文献（参考文献/） **react-19-migration.md** \- 详细的 React 19 重大更改和迁移步骤 **new-architecture-errors.md** \- 启用新架构时常见的构建错误 **expo-sdk-52-breaking.md** \- Expo SDK 52+ 特定重大更改 **当 Claude 应该加载这些时：** 当遇到迁移错误、构建失败或详细的 React 19 问题时 ### 资产（资产/） **new-arch-decision-tree.md** \- 用于选择 React Native 版本的决策树 **css-features-cheatsheet.md** \- 新 CSS 属性的完整示例 ** ** ## Expo SDK 52+ 详细信息 ### 重大变化 **JSC 从 Expo Go 中删除：** // 这在 Expo Go (SDK 52+) 中不再有效： { "jsEngine": "jsc" // ❌ 忽略，仅 Hermes } **Google 地图已从 Expo Go 中删除（SDK 53+）：** # 必须使用 Google 地图的自定义开发客户端 npx expo 安装 expo-dev-client npx 博览会运行：android **推送通知警告：** Expo Go 显示推送通知警告 - 使用自定义开发客户端进行生产测试。 ### 新功能（SDK 52） **expo/fetch（符合 WinterCG）：** 从'expo/fetch'导入{fetch}； // 符合标准的 Workers/Edge 运行时获取 const 响应 = 等待 fetch('https://api.example.com/data'); **反应导航 v7：** npm install @react-navigation/native@^7.0.0 ** ** ## 官方文档 * **反应本机**： * **博览会**： * **React 19**： * **新架构**： * **升级助手** : * **Context7 库 ID**：/facebook/react-native ** ** ## 软件包版本（2025-11-22 验证） { “依赖项”：{ “反应”：“^19.1.0”， "react-native": "^0.82.0", "世博会": "~52.0.0", "@react-navigation/native": "^7.0.0", "@reduxjs/toolkit": "^2.0.0", “react-i18next”：“^15.0.0” }, “开发依赖项”：{ "@types/react": "^19.0.0", “打字稿”：“^5.7.0” } } ** ** ## 故障排除 ### 问题：构建失败并显示“未找到 Fabric 组件描述符” **解决方案：** 库与新架构不兼容。检查库文档以获取新架构支持，或使用互操作层（仅限 0.76-0.81）。 ### 问题：“propTypes 不是函数”错误 **解决方案：** React 19 删除了 propTypes。请改用 TypeScript 进行类型检查。运行“npx @codemod/react-19 升级”。 ### 问题：console.log() 未显示在 Metro 终端中 **解决方案：** Metro 日志转发在 0.77 中删除。使用 React Native DevTools Console（按“j”）或“npx expo start --client-logs”（临时解决方法）。 ### 问题：iOS 构建期间出现 Swift AppDelegate 错误 **解决方案：** 将 `RCTAppDependencyProvider.sharedInstance()` 添加到 AppDelegate.swift。请参阅 Swift 迁移部分。 ### 问题：Redux 存储在启动时崩溃 **解决方案：** 使用 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 工具包（不是旧版 redux） * React-i18next（不是 i18n-js） * iOS 构建成功（如果是新项目则使用 Swift 模板） * Android构建成功 * 开发服务器运行无错误 * 所有导航/状态管理工作 ** ** **有问题吗？有问题吗？** 1. 检查 `references/new-architecture-errors.md` 是否有构建错误 2. 检查 `references/react-19-migration.md` 是否有 React 19 问题 3.查看官方文档： 4. 确保启用新架构（0.82+ 中强制） 5.验证所有依赖项都支持新架构 ** ** **填补知识空白：** 这项技能涵盖了法学硕士不知道的自 2024 年 12 月起的 React Native 更新。如果没有这项技能，Claude 会建议弃用的 API、删除的功能和过时的模式。

React Native 博览会

包含技能