upgrading-expo

upgrading-expo skill 概览

upgrading-expo skill 能做什么

upgrading-expo skill 旨在帮助你规划并执行 Expo SDK 升级，相比泛泛一句“怎么升级 Expo？”的提问，它能显著减少盲区。它聚焦的不是空泛建议，而是真正会花时间的升级工作：更新核心包、修复依赖版本漂移、清理陈旧缓存，以及排查 React、New Architecture、Native Tabs 和 expo-av 迁移中常见的破坏性变更。

谁适合使用 upgrading-expo

这个 upgrading-expo skill 最适合前端开发者、React Native 团队，以及负责维护现有 Expo 应用的 AI agent。它在你已经有项目、需要一条可执行的升级路径，而不是只看 release notes 摘要时最有价值。

最适合的使用场景包括：

• 在较新的 Expo SDK 版本之间升级
• 运行 expo install --fix 后修复安装失败或运行时故障
• 从 expo-av 这类已变更或拆分的包迁移出去
• 判断 React 19、Native Tabs 等特定 SDK 变更是否会影响你的代码库

这个 skill 真正解决的是什么问题

在评估 upgrading-expo for Frontend Development 时，用户通常想尽快得到这三个问题的答案：

1. 第一轮应该按什么命令顺序执行？
2. 哪些破坏性变更最可能打到我的应用？
3. 在我把时间耗进调试之前，应该先检查哪些文件或代码模式？

这个 skill 的价值在于，它把这些关键决策集中到一处，并且关联到具体的迁移参考资料。

它和通用升级提示词有什么不同

普通提示词可能只会建议你“升级 Expo 然后跑 doctor”。而 upgrading-expo skill 更进一步：它会从仓库中提取和版本强相关的迁移主题，包括：

• SDK 53+ 中 New Architecture 的默认行为
• SDK 54 中 React 19 的变化
• SDK 54+ 中 React Compiler 的配置
• SDK 55 中 Native Tabs API 的变化
• expo-av 在音频和视频上的替代迁移路径

因此，与宽泛的 React Native 排障提示相比，它更适合做有目标的升级工作。

安装前你需要知道的事

这个 skill 更偏“高质量指导”，而不是“自动化执行”。它不会附带脚本去自动检查你的 repo。它的核心价值来自整理好的升级流程，以及你可以直接套用到自己代码库的参考文档。
如果你要的是一键式 migrator，它并不适合；如果你要的是高信号、带具体迁移示例的升级清单，它会非常合适。

如何使用 upgrading-expo skill

upgrading-expo 的安装方式

如果你的 AI 环境支持 Skills，可以安装 Expo skills 仓库，然后从中调用 upgrading-expo。常见方式如下：

npx skills add https://github.com/expo/skills --skill upgrading-expo

如果你的工具链使用的是另一套 skill loader，就把它指向这个 repo 路径：
plugins/expo/skills/upgrading-expo

先看对的仓库文件

想要获得更实用的 upgrading-expo usage，建议按这个顺序阅读：

1. SKILL.md
2. references/new-architecture.md
3. references/react-19.md
4. references/react-compiler.md
5. references/native-tabs.md
6. references/expo-av-to-audio.md
7. references/expo-av-to-video.md

这个阅读顺序对应的是最常见的升级阻塞点：先看架构和 React 层面的变化，再看具体功能模块迁移。

先跑一遍 upgrading-expo 的核心升级顺序

这个 skill 给出的基础升级流程很短，但在深入排查前非常值得先完整执行一遍：

npx expo install expo@latest
npx expo install --fix
npx expo-doctor
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

之所以重要，是因为：

• expo@latest 会先把 SDK 对齐
• --fix 会修正 Expo 管理下的包版本
• expo-doctor 能尽早发现兼容性问题
• 清缓存可以清掉旧的 Metro / native 状态，避免它们伪装成升级 bug

如果你在 Linux 上，或者没有使用 Watchman，请按你的环境调整清理步骤。

什么时候该用 preview 版本

这个 skill 也说明了 Expo beta 版本的安装方式：通过 @next 使用带 .preview 后缀的版本。
如果你是在验证即将发布的 SDK，或者测试一个还没进 stable 的修复，这会很有帮助。

npx expo install expo@next --fix

但请务必有意识地这么做。对于生产应用来说，preview 升级不应该成为默认选项，除非你明确是在试用 pre-release。

提供 upgrading-expo 真正需要的输入

想让 upgrading-expo guide 给出高质量结果，你需要把当前状态和目标状态说清楚。至少提供这些信息：

• 当前 Expo SDK 版本
• 使用的 package manager
• 你用的是 Expo Go 还是 development builds
• 是否运行 prebuild
• 关键依赖：expo-router、expo-av、react-native-reanimated、自定义 native modules
• 当前安装、构建或运行时报出的错误
• 是否存在 iOS、Android 或 web 的平台特定故障

没有这些上下文，输出通常只能停留在泛泛建议。

把模糊目标改写成高质量提示词

弱提示词：

Upgrade my Expo app.

更强的提示词：

Use the upgrading-expo skill to move my app from Expo SDK 53 to 54. We use expo-router, expo-av, Reanimated, and development builds. After npx expo install --fix, expo-doctor reports dependency mismatches and our app fails on startup with video playback errors. Tell me the likely breaking changes, the commands to run in order, and the code areas I should inspect first.

这个写法更有效，因为它：

• 明确指出源 SDK 和目标 SDK
• 列出了高风险依赖包
• 要求的是“带优先级的输出”，而不是泛泛建议

把你的应用映射到对应参考文档

只有当你有意识地把依赖面和参考文档对应起来时，仓库里的 references 才会真正发挥价值：

• 如果你用 expo-av 做声音播放或录音，读 references/expo-av-to-audio.md
• 如果你用 expo-av 播放视频，读 references/expo-av-to-video.md
• 如果你要升到 SDK 55，并使用 expo-router/unstable-native-tabs，读 references/native-tabs.md
• 如果你正进入 SDK 53+ 或 54+，且项目里有 native modules，读 references/new-architecture.md
• 如果你在 SDK 54 上，references/react-19.md 和 references/react-compiler.md 都要看

这正是这个 skill 相比“快速扫一眼 repo”更有信息增量的地方。

重点盯住 upgrading-expo 覆盖的高风险区域

在实际项目里，这个 skill 反复指出的高频断点主要有：

• SDK 升级后包版本没有对齐
• 旧 native modules 与 New Architecture 不兼容
• Reanimated 配置变化，包括 SDK 54+ 里的 react-native-worklets
• React 19 在应用代码或库代码中的 API 变化
• expo-av 迁移到 expo-audio 和 expo-video
• Native Tabs 在 router 层面的 UI 变化

如果你的应用涉及其中任意一项，建议直接让 skill 产出“针对性的迁移检查清单”，不要只要一份泛化的升级摘要。

用两轮式工作流来跑 upgrading-expo

一种效果很好的 upgrading-expo usage 方式是：

1. 先根据你的版本和依赖，让它给出升级方案
2. 按顺序执行命令
3. 把精确报错贴回来，让它进一步收敛成修复方案

当你能提供来自 expo-doctor、TypeScript、Metro 或 native builds 的具体输出时，这个 skill 在结构化排障上会明显更强。

留意 upgrading-expo 暗示的 release-note 型问题

这个 skill 的破坏性变更清单，其实已经指向了你应该重点审查的区域：

• 被移除的 API
• 变化的 import 路径
• 需要 prebuild 的 native module 变更
• camera、audio、video 相关回归
• navigation 回归

这意味着你的代码审查不能只停在 package.json。在真正运行应用前，先在代码库里搜索受影响的 imports 和组件。

在 prebuild 和原生代码场景下要更谨慎地用 upgrading-expo

如果你的应用有自定义 native modules 或 config plugins，upgrading-expo skill 依然有用，但要预期除了 markdown references 之外，你还需要做额外工作。
在这类项目中，建议让 skill 明确拆分出：

• 仅 JS 层面的迁移任务
• prebuild 重新生成相关任务
• 原生依赖兼容性检查

这样能显著减少升级过程中的混乱。

upgrading-expo skill 常见问题

upgrading-expo 适合新手吗？

适合，前提是你已经有一个 Expo 项目，并且能提供基本项目情况。它不是完整的 Expo 教程，而是聚焦升级的指南。对新手来说，如果你能给出当前 SDK 版本、报错信息和主要依赖，通常会得到更好的结果。

upgrading-expo skill 的边界在哪里？

这个 skill 主要帮助你做升级规划、梳理命令顺序，以及识别已知迁移热点。它不会自动扫描整个 repo，也不能保证所有第三方原生库都兼容。
如果遇到更深层的原生问题，你仍然可能需要查看具体包的文档和 GitHub issues。

它和直接让 LLM 帮我升级 Expo 有什么区别？

核心区别在于“整理和指向性”。upgrading-expo skill 会把模型引导到 Expo 特定的迁移参考资料上，而这些内容是通用提示词很容易漏掉的，尤其是 expo-av、React 19、React Compiler、Native Tabs 和 New Architecture 相关变化。

什么情况下不该用 upgrading-expo？

以下情况建议跳过：

• 你是在新建 Expo 应用，而不是升级已有应用
• 你的问题和 SDK 升级无关
• 你需要的是自动化 codemod 或 CLI 迁移工具
• 你的主要阻塞点是某个单独的第三方 native library，且它有自己独特的迁移步骤

upgrading-expo 支持 preview SDK 吗？

支持。这个 skill 提到 beta 版本使用 .preview 后缀，并通过 @next 安装。
这对测试即将到来的变化很有帮助，但对大多数场景来说，stable 升级仍然是更安全的默认选择。

upgrading-expo 只适用于 managed workflow 吗？

不是。它对 managed 和基于 prebuild 的 Expo 应用都适用。
但如果你用了 prebuild 或自定义原生代码，通常意味着你还需要额外做一些手动兼容性检查。

如何改进 upgrading-expo skill 的使用效果

明确告诉 upgrading-expo 你的版本跨度

最能提升结果质量的一点其实很简单：直接说明“从 SDK X 到 SDK Y”，不要只说“升级 Expo”。
很多迁移建议会因为你是否跨入 SDK 53、54 或 55 而发生明显变化。

提供会改变答案的包依赖面

想让 upgrading-expo 给出更准确的结果，请把会触发对应参考文档的依赖一起提供出来：

• expo-av
• expo-router
• react-native-reanimated
• 自定义 native modules
• 任何在 expo-doctor 中报错的包

这样它才能从通用检查清单，进一步收敛成“哪些地方最可能受影响”的具体建议。

贴真实诊断信息，不要只做转述

不理想：

build failed after upgrade

更好：

npx expo-doctor says package versions are invalid, Metro reports unresolved import from expo-av, and iOS dev build fails after enabling New Architecture.

精确日志能帮助这个 skill 区分：到底是依赖漂移问题，还是 API 迁移问题。

要求输出带优先级

一个很好用的请求结构是：

1. 现在该跑哪些命令
2. 最可能出现的破坏性问题，按概率排序
3. 应该搜索哪些文件 / imports
4. 修复后如何验证

这种结构会让 upgrading-expo guide 在时间紧张时更容易落地执行。

把安装失败和代码迁移拆开处理

一个很常见的失败模式，是把包安装问题和源码级 API 变化混在一起。建议让 skill 按这个顺序处理：

• 依赖对齐
• doctor 输出
• 缓存重置
• 源码迁移
• 运行时验证

这样可以减少来回打转式调试。

直接让 upgrading-expo 给出代码库搜索模式

提升 upgrading-expo skill 输出质量的最好办法之一，就是让它给出 grep 风格的搜索目标。例如：

Using the upgrading-expo skill, list the import paths, component names, and hooks I should search for to migrate from expo-av and to verify Native Tabs changes in SDK 55.

这样就能把宽泛建议转换成可执行的代码审查任务。

第一轮完成后，重点验证高风险路径

第一次升级尝试之后，请务必专项测试这些区域：

• 音频播放和录音
• 视频播放
• tab 导航
• 在 Expo Go 和 dev build 下的启动情况
• 任何大量使用动画或 native modules 的页面

这些都是最容易暴露 SDK 迁移问题、也是这个 skill 明确覆盖的区域。

用更窄的后续提示词持续迭代

不要反复让这个 skill “解决整个升级过程”。第二轮开始，范围要主动收窄：

• “只关注我共享 UI package 里的 React 19 变更”
• “只关注 expo-av 的视频迁移”
• “只关注 New Architecture 不兼容问题”

范围越小，通常越容易得到更清晰、更准确的修复步骤。