Nx 工作区中 Expo SDK 53 升级迁移到 SDK 54 的完整指南【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx导读本文以 Nx 官方仓库 ai-instructions-for-expo-54.md 为核心骨架系统讲解如何将一个包含多个 Expo 应用的 Nx Monorepo 工作区从 Expo SDK 53 平滑迁移到 SDK 54。文章覆盖迁移前检查、九大类破坏性变更的逐一处理、Jest 与版本对齐、迁移后验证以及常见问题排查并补充nx/expo插件源码级证据迁移实现与测试帮助读者尤其是 AI Agent/LLM 执行者按部就班地完成一次可验证、可回滚的 SDK 升级。在 Nx 仓库中这份文档并非普通说明而是被注册为一条可执行迁移指令在 migrations.json 中update-22-2-0-create-ai-instructions-for-expo-54迁移通过prompt字段引用该 Markdown 文件同时配套update-22-2-0-add-expo-system-ui、update-22-2-0-update-jest-for-expo-54两条自动化迁移均要求expo 54.0.0以及22.2.0的packageJsonUpdates版本更新。也就是说Nx 既提供自动化的代码改动也把这份给 LLM 的迁移指引作为执行手册交付给 AI Agent。理解这一点有助于读者把它当作一套先自动化、后人工核对的完整升级流程。迁移前检查清单Pre-Migration Checklist在动手之前先完成四项摸底工作确定迁移的波及范围1. 识别工作区中的所有 Expo 项目Expo 应用通常带有start目标因此可以一次性列出nx show projects --with-target start2. 定位所有 Expo 配置文件搜索app.json或app.config.{js,ts}搜索metro.config.{js,ts}检查各项目的project.json中是否包含 Expo 相关配置如start、run-ios、run-android、export、prebuild等目标3. 识别受影响代码从expo-av导入的文件音频/视频功能从expo-file-system导入的文件使用StatusBar配置的代码Android 特有的布局代码涉及安全区域从expo/vector-icons导入的文件4. 检查是否存在 Detox E2E 测试项目在package.json依赖中搜索detox查找detox.config.js或.detoxrc.js文件建议同时记录每个应用package.json中expo的当前版本号作为迁移前后对比的基线。重要警告Detox E2E 测试暂不支持Expo SDK 54 目前不支持 Detox 进行端到端测试。如果工作区包含 Detox 项目需要明确以下影响影响迁移到 Expo SDK 54 后使用 Detox 的 E2E 测试将无法工作。检测方式检查package.json中是否存在detox依赖或项目中是否存在detox.config.js。必须执行的动作检测到 Detox 项目时务必先征询用户意见再继续迁移。建议的询问文案可直接引用Your workspace contains Detox E2E tests. Detox is not currently supported in Expo SDK 54. Do you want to proceed with the migration knowing that Detox tests will not work until Detox adds SDK 54 support?可考虑的替代方案如果 Detox E2E 测试对工作流至关重要留在 Expo SDK 53等待 Detox 增加 SDK 54 支持后再升级考虑迁移到Maestro做 E2E 测试已支持 Expo SDK 54。迁移步骤九大类破坏性变更逐一处理1. expo-av 拆分迁移到 expo-audio 与 expo-videoexpo-av已被弃用拆分为expo-audio与expo-video两个独立包。搜索模式import.*from []expo-av[]根据实际用途分别处理。1.1 音频迁移// BEFORE (Expo SDK 53) import { Audio } from expo-av; const sound new Audio.Sound(); await sound.loadAsync(require(./audio.mp3)); await sound.playAsync(); // AFTER (Expo SDK 54) import { useAudioPlayer } from expo-audio; function AudioComponent() { const player useAudioPlayer(require(./audio.mp3)); const play () player.play(); const pause () player.pause(); return Button onPress{play} titlePlay /; }行动清单安装expo-audionpx expo install expo-audio若expo-av仅用于音频将其移除用useAudioPlayerHook 替换Audio.Sound用useAudioRecorderHook 替换Audio.Recording更新播放控制方法playAsync→play等将基于类的音频处理改为基于 Hook 的写法1.2 视频迁移// BEFORE (Expo SDK 53) import { Video } from expo-av; function VideoPlayer() { return ( Video source{{ uri: https://example.com/video.mp4 }} style{{ width: 300, height: 200 }} useNativeControls resizeModecontain / ); } // AFTER (Expo SDK 54) import { VideoView, useVideoPlayer } from expo-video; function VideoPlayer() { const player useVideoPlayer(https://example.com/video.mp4, (player) { player.loop true; player.play(); }); return ( VideoView player{player} style{{ width: 300, height: 200 }} nativeControls contentFitcontain / ); }行动清单安装expo-videonpx expo install expo-video若expo-av仅用于视频将其移除用VideoViewuseVideoPlayer替换Video组件将resizeMode属性替换为contentFit将useNativeControls属性替换为nativeControls视频控制方法改用 player 实例调用2. expo-file-system 导入路径变更Expo SDK 54 中expo-file-system的新 API此前位于/next子路径已转为稳定 API导入路径相应简化。搜索模式import.*from []expo-file-system/next[]。// BEFORE (Expo SDK 53) import { File, Directory } from expo-file-system/next; // AFTER (Expo SDK 54) import { File, Directory } from expo-file-system;行动清单将所有expo-file-system/next导入替换为expo-file-system验证 API 兼容性该 API 现已稳定3. StatusBar 配置移除改用 expo-system-uiSDK 54 中expo-status-bar的配置方式发生变化app.json中的userInterfaceStyle会直接影响状态栏主题。搜索模式app.json或app.config.*中的userInterfaceStyle。// BEFORE (Expo SDK 53) { expo: { userInterfaceStyle: automatic, ios: { userInterfaceStyle: light }, android: { userInterfaceStyle: dark } } } // AFTER (Expo SDK 54) // userInterfaceStyle 改由 expo-system-ui 处理 // 如需程序化控制使用// AFTER (Expo SDK 54) - 程序化控制 import * as SystemUI from expo-system-ui; // 设置根视图背景色 SystemUI.setBackgroundColorAsync(#ffffff);行动清单安装expo-system-uinpx expo install expo-system-ui审查app.json中的userInterfaceStyle设置如需程序化控制将 UI 风格处理迁移到expo-system-ui源码佐证Nx 为此提供了自动化迁移 add-expo-system-ui.ts其逻辑是遍历getProjects得到的所有项目仅对projectType application且package.json中存在expo依赖的 Expo 应用在其dependencies中补写expo-system-ui: ~6.0.0若已存在则跳过。对应测试 add-expo-system-ui.spec.ts 覆盖了为 Expo 应用添加依赖已存在时不覆盖跳过非 Expo 项目跳过 library 项目无 package.json 时不抛错五种场景可见该迁移设计得足够保守。4. Android Edge-to-Edge UI默认开启Expo SDK 54 在 Android 上默认启用 edge-to-edge 显示内容会延伸到系统栏状态栏和导航栏之下。搜索模式Android 特有样式、安全区域处理、padding/margin 调整。// BEFORE (Expo SDK 53) - 隐式安全区域 function App() { return ( View style{{ flex: 1 }} TextContent/Text /View ); } // AFTER (Expo SDK 54) - 显式安全区域处理 import { SafeAreaView } from react-native-safe-area-context; // 或 import { useSafeAreaInsets } from react-native-safe-area-context; function App() { return ( SafeAreaView style{{ flex: 1 }} TextContent/Text /SafeAreaView ); } // 或者用 Hook 获得更精细的控制 function App() { const insets useSafeAreaInsets(); return ( View style{{ flex: 1, paddingTop: insets.top, paddingBottom: insets.bottom }} TextContent/Text /View ); }行动清单审计所有屏幕组件的安全区域处理若未安装安装react-native-safe-area-context用SafeAreaProvider包裹根组件在内容触及屏幕边缘处添加SafeAreaView或使用useSafeAreaInsets在 Android 真机/模拟器上验证 UI 不与系统栏重叠特别关注以下位置顶部 Header 组件底部导航 / Tab 栏Modal 组件全屏媒体播放器5. React Native Reanimated 版本决策Expo SDK 54 同时支持 Reanimated v3 与 v4。如果使用 New Architecture应升级到 v4。搜索模式package.json中的react-native-reanimated、worklet 函数。Reanimated v3稳定版npx expo install react-native-reanimated3Reanimated v4New Architecture 推荐npx expo install react-native-reanimated4行动清单检查项目是否启用了 New Architecture使用 New Architecture 则升级到 Reanimated v4停留在旧架构则继续使用 Reanimated v3升级后全面测试所有动画6. expo/vector-icons 校验SDK 54 中expo/vector-icons的部分图标可能被重命名或移除。搜索模式import.*from []expo/vector-icons[]。行动清单运行应用在控制台检查缺失图标的警告搜索可能变更的图标名称按需更新图标名称参考 Expo 官方 Vector Icons 目录icons.expo.fyi查找替代图标7. React 19.1 兼容性Expo SDK 54 使用React 19.1和React Native 0.81。搜索模式React.FC、已废弃的生命周期方法、旧版 Context API。// BEFORE - React.FCReact 19 中不推荐 const MyComponent: React.FCProps ({ title }) { return Text{title}/Text; }; // AFTER - 直接函数类型标注 function MyComponent({ title }: Props) { return Text{title}/Text; } // 或显式声明返回类型 const MyComponent ({ title }: Props): React.ReactElement { return Text{title}/Text; };行动清单为 React 19.1 更新 TypeScript 类型types/react~19.1.0移除React.FC模式可选但推荐检查废弃的生命周期方法并改用 Hooks验证第三方库与 React 19.1 的兼容性8. Metro 配置更新Expo SDK 54 使用Metro 0.83并带更新的配置。搜索模式metro.config.{js,ts}。// BEFORE (Expo SDK 53) const { getDefaultConfig } require(expo/metro-config); const config getDefaultConfig(__dirname); // AFTER (Expo SDK 54) - API 相同但需验证兼容性 const { getDefaultConfig } require(expo/metro-config); const config getDefaultConfig(__dirname); // 确保自定义 transformer 兼容 Metro 0.83行动清单更新expo/metro-config更新metro-config至~0.83.0更新metro-resolver至~0.83.0测试自定义 Metro 插件/transformer 的兼容性9. Babel 配置清理Expo SDK 54 将babel-preset-expo升级到新版本。搜索模式babel.config.js、.babelrc。行动清单更新babel-preset-expo版本移除任何已废弃的 Babel 插件Babel 变更后清空 Metro 缓存npx expo start --clear目标版本对齐以仓库 migrations.json 为准原迁移文档给出的是通用指引而 Nx 仓库本身维护着一份精确到每个依赖的版本常量表。在执行第 79 类变更时应参照 migrations.json 中22.2.0的packageJsonUpdates要求expo 53.0.0 54.0.0以及 versions.ts 中 Expo v54 常量逐项对齐版本依赖SDK 53升级前SDK 54升级目标expo~53.0.10~54.0.0react^19.0.0^19.1.0react-native~0.79.30.81.5types/react~19.0.10^19.1.0react-native-web~0.20.0~0.21.0expo-system-ui~5.0.8~6.0.8expo-status-bar~2.2.3~3.0.8expo-splash-screen~0.30.9~31.0.11expo/cli~0.24.14~54.0.16babel-preset-expo~13.2.0~54.0.7jest-expo~53.0.7~54.0.13expo/metro-config~0.20.14~54.0.9metro-config—~0.83.0metro-resolver—~0.83.0testing-library/react-native~13.2.0~13.2.0两点说明原文档中更新expo/metro-config至~0.22.0与更新babel-preset-expo至~14.0.0采用的是 Expo 官方自有的版本号体系而在本仓库的迁移数据中对应版本为~54.0.9与~54.0.7见 migrations.json 与 versions.ts 的expoV54MetroConfigVersion、babelPresetExpoV54Version常量。迁移时以npx expo install --fix解析出的真实兼容版本为准再与上表核对。versions.ts 中minSupportedExpoVersion 53.0.0表明nx/expo插件的最低支持版本即 SDK 53而 package.json 的peerDependencies同样声明expo 53.0.0说明本插件为 53→54 的迁移提供了完整支撑。迁移后验证Post-Migration Validation1. 清空所有缓存# 清空 Expo 缓存 npx expo start --clear # 清空 Metro bundler 缓存在项目工作区目录内执行 rm -rf node_modules/.cache/metro-* # 需要时清空 Nx 缓存 nx reset2. 逐项目运行测试# 单独测试每个项目 nx run-many -t test -p PROJECT_NAME3. 运行全部受影响项目的测试# 运行所有受影响项目的测试 nx affected -t test4. 在真机/模拟器上验证# iOS nx run PROJECT_NAME:run-ios # Android nx run PROJECT_NAME:run-android5. 复核迁移检查清单所有expo-av用法已迁移到expo-audio或expo-video所有expo-file-system/next导入已更新Android 安全区域处理已验证所有图标引用已验证React 19.1 兼容性已验证Metro 与 Babel 配置已更新所有测试通过应用可在 iOS 模拟器/真机运行应用可在 Android 模拟器/真机运行Jest 配置的自动化迁移与手工核对文档正文未展开但 Nx 仓库为 SDK 54 专门实现了 Jest 相关迁移 update-jest-for-expo-54.ts其改动恰好对应迁移后验证中的跑测试环节建议迁移时一并核对移除自定义 resolver从jest.config.{ts,cts,js}中删除resolver属性仅当配置同时包含jest-expopreset 和jest.resolver.js引用时。删除jest.resolver.js文件SDK 54 不再需要此前update-21-4-0-add-jest-resolver引入用于处理 Expo winter runtime 的 resolver。更新src/test-setup.ts追加jest.mock(expo/src/winter/ImportMetaRegistry, ...)的 mock以及global.structuredClone的 polyfill缺失时用JSON.parse(JSON.stringify(...))兜底且保证幂等——已存在则不重复注入同时保留用户原有 setup 内容。清理 tsconfig从tsconfig.app.json/tsconfig.lib.json/tsconfig.json的exclude与tsconfig.spec.json的include中移除jest.resolver.js引用。对应测试 update-jest-for-expo-54.spec.ts 覆盖了Expo 项目正确更新非 Expo 项目不动无 resolver 的 Expo 项目不动保留已有 test-setup 内容JS 项目同样处理mock 不重复注入test-setup.ts 不存在时自动创建七类场景。手工迁移时可以对照这份清单检查自己的 Jest 配置。常见问题与解决方案问题解决方案组件卸载时音频播放停止新版useAudioPlayerHook 会自动管理清理。如需持续播放考虑用 Context 或状态管理方案持有播放器实例视频播放器显示黑屏确保使用useVideoPlayerVideoView组合检查视频源 URL 是否正确且可访问内容被 Android 导航栏遮挡用react-native-safe-area-context的SafeAreaView包裹屏幕内容或用useSafeAreaInsets设置自定义 padding升级后图标缺失对照 Expo Vector Icons 目录icons.expo.fyi查找被重命名/移除的图标并更新引用React 19.1 的 TypeScript 报错将types/react更新到~19.1.0检查并移除React.FC等废弃模式Metro bundler 无法启动用npx expo start --clear清空所有缓存并确保 Metro 相关包版本兼容需要审查的文件清单用以下命令建立待审文件清单# 配置文件 find . -name app.json -o -name app.config.* find . -name metro.config.* find . -name babel.config.* # 包含 expo-av 导入的文件 rg from [\]expo-av[\] --type ts --type tsx --type js # 包含 expo-file-system/next 导入的文件 rg from [\]expo-file-system/next[\] --type ts --type tsx --type js # 包含 vector-icons 导入的文件 rg from [\]expo/vector-icons[\] --type ts --type tsx --type js # 安全区域相关文件 rg SafeAreaView|useSafeAreaInsets --type ts --type tsx --type js大型工作区的迁移策略分阶段迁移先迁移一个小项目验证流程再逐步铺开使用功能分支为不同迁移方面创建独立分支如migrate/audio-video、migrate/jest便于隔离问题与回滚频繁运行测试每次配置变更后运行受影响的测试nx affected -t test记录问题持续记录项目特有的问题与解决方案沉淀到文档真机测试Android edge-to-edge 的布局变化必须依赖真机验证迁移期间的常用命令速查# 找出所有 Expo 项目 nx show projects --with-target start # 启动指定项目 nx start PROJECT_NAME # 变更后测试指定项目 nx test PROJECT_NAME # 测试所有受影响项目 nx affected -t test # 查看项目详情Web 界面 nx show project PROJECT_NAME --web # 需要时清空 Nx 缓存 nx reset # 清空 Expo 缓存 npx expo start --clear面向 LLM/AI Agent 的执行要点当 AI Agent 执行本次迁移时请遵循以下原则这也是 Nx 将本文档注册为迁移 prompt 的初衷系统化推进一次只完成一个类别完成后再进入下一类每步变更后测试不要把所有改动批量堆叠后再统一验证保持用户知情在每个小节推进时同步进度包括上文 Detox 场景的强制询问及时处理错误测试失败立即修复再继续后续步骤更新文档记录工作区特有的模式或问题有意义的提交将相关变更分组配合清晰的信息提交例如按类别分 commit使用 TodoWrite 工具将迁移进度可视化追踪双平台测试Expo 的变更经常对 iOS 与 Android 产生不同影响两端都要验证延伸阅读完成 SDK 54 迁移后可参考同系列的新版迁移指引 ai-instructions-for-expo-56.md对应 Nx 23.1.0 的迁移涉及expo/metro取代独立 metro-config 等变更了解后续版本演进方向。整个迁移体系可结合 migrations.json 查看各版本迁移的注册关系形成对nx/expo升级机制的完整认知。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考