React Native 0.83迁移问题故障排除
本文档将指导您解决在将应用迁移到React Native 0.83时会遇到的常见错误。
npm错误
ERESOLVE — 对等依赖项解析失败
错误： ERESOLVE无法解析依赖关系树
修复：
- 全新安装：
rm -rf node_modules package-lock.json npm install - 如果仍失败，请根据错误输出 ("已发现： X" vs " 无法解决： Y") 来识别冲突
- 确保所有依赖版本均符合目标版本RN 0.83的要求
- 切勿使用
--legacy-peer-deps— 它会掩盖冲突，进而导致运行时错误。
对等React版本冲突（已缓存0.72）
错误：peer react@... from react-native@0.72或Conflicting peer dependency: react@19
原因： node_modules中已缓存的react-native@0.72.0与React 19冲突。
修复：
rm -rf node_modules package-lock.json
验证package.json是否为"react": "19.2.0", "react-native": "0.83.0", "@types/react": "^19.2.0".
@types/react版本不匹配
错误： Found: @types/react@18 / peerOptional @types/react@^19
修复： 更新devDependencies：
"@types/react": "^19.2.0",
"@types/react-test-renderer": "^19.1.0"
ts-jest对等依赖项冲突
错误：peer jest@^28.0.0 from ts-jest
修复： 更新ts-jest以匹配jest v29：
"ts-jest": "^29.1.0"
TypeScript错误
未找到tsconfig.json扩展
错误： TS6053: 未找到文件 '@react-native/typescript-config/tsconfig.json'
修复：
"extends": "@react-native/typescript-config"
（移除/tsconfig.json后缀）
allowImportingTsExtensions / customConditions
错误： TS5096或TS5098
修复： 向tsconfig.json添加覆盖项：
"compilerOptions": {
"moduleResolution": "bundler",
"allowImportingTsExtensions": false
}
使用isolatedModules重新导出类型
错误： TS1205： 启用 'isolatedModules' 时重新导出类型
修复：
export type { Cookie } from './types/CookieManagerTypes';
CMake和原生版本错误
未找到keplerscript目标
错误： 目标链接到keplerscript-2，但未找到目标
修复： 在cxx/CMakeLists.txt中：
# 更改所有参考：
keplerui::keplerscript-2 → keplerui::keplerscript-4
不支持C++20功能
错误： 不支持C++20功能
修复： 确保已安装CMake 3.22以上版本，且支持C++20编译器（GCC 10以上版本或Clang 12以上版本）。
Metro Bundler错误
找不到模块 '@react-native/babel-preset'
修复：
rm -rf node_modules
npm install
npm start -- --reset-cache
无法解析模块
修复：
rm -rf node_modules/.cache
npm start -- --reset-cache
Jest错误与测试错误
SyntaxError： 无法在模块（平台包）之外使用导入语句
原因：@amazon-devices/react-native-kepler@4.0.0在其Jest设置中使用了ES模块。
修复： 在jest.config中的transformIgnorePatterns中添加：
"node_modules/(?!((jest-)?react-native|@react-native(-community)?|@amazon-devices/react-native-kepler)|react-native-safe-area-context)"
无法读取未定义的属性 (Dimensions/PixelRatio/StyleSheet)
原因： React 19更改了模拟行为。这些API无法自动模拟。
修复： 添加模拟到jest.setup.js（请参阅步骤7.2）。
无法在已卸载的测试渲染器上访问.root
原因： 将@testing-library/react-native render()包装在ReactTestRenderer.act()中。
修复： 移除act()包装—由测试库内部处理（请参阅步骤7.4）。
缺失NativeAnimatedModule方法存根
错误： 在NativeAnimatedHelper.js中无法读取未定义的属性（读取 'apply'）
原因： RN 0.83动画系统在NativeAnimatedModule上调用了23种特定方法。
修复： 添加完整模拟到（请参阅步骤7.2）。
导航栈计时器泄漏
错误： 您正在尝试在Jest环境拆除后导入文件
修复：
beforeEach(() => jest.useFakeTimers());
afterEach(() => {
jest.runOnlyPendingTimers();
jest.useRealTimers();
});
已在keplerscript-native-ui-components中嵌套react-native
错误： keplerscript-native-ui-components/node_modules/react-native发生Flow/ESM解析错误
原因：kepler-ui-components@2.x捆绑了自身的react-native副本。
修复： 更新到@amazon-devices/kepler-ui-components@3.0.0版本。
运行时错误
运行时模块加载失败： IKeplerScript_2_0
原因：manifest.toml仍引用旧版Kepler 2.x运行时。
修复： 更新manifest.toml中的runtime-module路径（请参阅第4阶段）。
未找到模块'@amazon-devices/keplerscript-commonmodules'
修复： 添加到devDependencies：
"@amazon-devices/keplerscript-commonmodules": "^1.0.0"
无法识别的build-kepler命令
原因：已移除@react-native-community/cli。
修复： 保留devDependencies：
"@react-native-community/cli": "11.3.2"
ReferenceError：未定义useState
修复： 添加显式导入：
import React, { useState, useEffect, useCallback } from 'react';
Last updated: 2026年7月9日
