eas-update

EAS Update

EAS 服务 — 需付费。 EAS Update 可在 Free 计划中使用；发布和交付会消耗更新、带宽和存储配额，付费计划的限额更高。请参阅 https://expo.dev/pricing。

使用 EAS Update，可向已安装的应用交付兼容的 JavaScript、样式和资源变更，而无需提交新的原生二进制文件。原生代码变更仍需要新的构建。

从受支持的配置流程开始

进行任何更改之前，请检查 package.json、Expo 应用配置、eas.json（如果存在），以及 ios/ 或 android/ 是否已纳入版本控制。审核 CLI 的更改时，请依据检查结果：

• 保留现有的动态或特定平台的应用配置。
• 如果存在 eas.json，请保留其配置文件和现有的通道分配。CLI 只会为尚未指定通道的构建配置文件添加与配置文件名称匹配的通道。
• 如果不存在 eas.json，请勿手动创建。CLI 可能会提示用户单独运行 eas build:configure。
• 如果原生项目已纳入版本控制，CLI 应会同步平台的原生 Update 配置。如果没有，则应由连续原生生成在之后的构建中应用原生配置。

安装软件包或解读特定版本的行为之前，请先检测 Expo SDK 版本。

如果尚未安装 expo-updates，请安装与 SDK 兼容的版本：

npx expo install expo-updates

在项目根目录中进行配置：

npx eas-cli@latest update:configure

请使用 eas update:configure，不要手动编造 updates.url、runtimeVersion、原生元数据或构建配置文件通道。该命令能够处理 EAS 项目关联、连续原生生成，以及已提交原生目录的项目。请检查并说明命令产生的差异。

如果项目尚未关联，或用户尚未授权所需的远程操作，导致命令无法继续，请在完成任何独立且有效的软件包安装后停止，并说明尚需完成的事项。不要通过手动添加运行时版本策略、配置插件、更新 URL 或通道来部分仿照 update:configure。

对于动态应用配置、非 EAS 构建，或无法自动完成的命令，请遵循当前设置文档，不要猜测：https://docs.expo.dev/eas-update/getting-started.md。

理解各个概念

• **构建：**已安装的原生应用。它包含原生代码、内嵌更新、平台、运行时版本，以及通常在构建时固定的通道。
• **更新：**针对某个平台和运行时版本发布的 JavaScript 包、资源和元数据。
• **分支：**按顺序排列的更新流。最新的兼容更新处于活动状态。
• **通道：**内嵌在构建中的稳定部署目标。在服务端，通道指向一个分支。
• **运行时版本：**更新与构建中原生代码之间的兼容性边界。

只有在平台和运行时版本匹配，且构建的通道指向包含该更新的分支时，构建才会收到更新：

installed build (channel: production, runtime: 1.1.1, platform: ios)
  -> production channel
  -> production branch
  -> newest update for runtime 1.1.1 and ios

通道和分支通常名称相同，但它们是不同的对象。eas channel:edit 会更改服务端上某个通道的分支映射，影响该通道上的所有构建。它不会更改单个安装中内嵌的通道。

请依据这个模型作出判断，但应根据用户的请求，仅解释所需概念，而不是每次都完整复述整个模型。

判断更新是否兼容

对于已安装的原生运行时已支持的 JavaScript、样式和打包资源变更，请使用更新。

如果变更新增或修改了原生代码或原生配置（包括大多数原生库新增和 SDK 升级），请创建新的原生构建。不要试图绕过运行时不匹配问题，也不要暗示发布更新可以为现有构建添加原生功能。请参阅 https://docs.expo.dev/eas-update/runtime-versions.md。

不要把更改项目的运行时版本策略当作顺手的修复。请说明当前策略如何影响兼容性；将更改策略视为单独的决策，因为它会改变哪些已安装的构建可以接收未来的更新。

谨慎发布

依赖记忆中的标志之前，请先查看当前 CLI 帮助：

npx eas-cli@latest update --help

对于常见的基于 channel 的流程：

npx eas-cli@latest update \
  --channel <channel> \
  --message "<message>" \
  --environment <environment>

SDK 55 及更高版本要求发布时指定 EAS 环境。请有意选择环境，确保导出的代码获得预期变量。

发布会更改远程状态，并可能影响已安装的应用。运行发布命令之前，请确认具体的项目、channel、环境、平台、运行时版本和消息。只有在用户明确要求或批准后，才发布到生产环境；如果授权或目标不明确，请在运行命令前停下来询问。不要仅凭当前 Git 分支推断生产发布目标。

请优先使用 preview 或 staging channel 进行验证。推广经过测试的更新时，请使用文档所述的部署流程，尽可能确保生产环境收到相同的制品：https://docs.expo.dev/eas-update/deployment.md。

根据构建类型进行测试

开发构建

使用开发构建的 Extensions UI、EAS 仪表板或 Expo Orbit 预览更新。普通的 expo-dev-client 开发构建不会像发布构建那样自动启动更新。

Preview、TestFlight 和生产构建

发布构建通常会优先保证启动速度。使用默认启动行为时，应用可能会先启动当前内置或缓存的更新，同时在后台下载新发布的更新。下载的更新会在之后重启时应用。

进行手动 QA 时，请彻底终止应用（不要仅将其置于后台），然后重新打开，并留出时间让更新完成下载；如果更改仍未显示，请再彻底终止并重新打开一次。应将此描述为最多两次冷启动，而不是 TestFlight 专属流程：

1. 第一次启动可以发现并下载更新。
2. 接下来的启动可以运行已下载的更新。

不要为了避免第二次启动而自动更改 fallbackToCacheTimeout。启动时等待会以启动延迟和可靠性为代价，加快更新生效。如果应用需要有意设计的更新体验，可以考虑使用 expo-updates API 检查、获取更新，并显示非阻塞式的重启操作。请使用与项目检测到的 SDK 版本相对应的 expo-updates API 参考文档。

排查构建未更新的问题

请按以下顺序检查：

1. 确认更新已发布到预期的 EAS 项目、channel 或 branch、平台和环境。
2. 比对已安装构建的平台和运行时版本与已发布更新。
3. 确认构建实际包含预期的更新 URL 和 channel；app-config 变更只有在重新编译构建后才会生效。
4. 检查 channel 到 branch 的映射，以及该 branch 上当前生效的更新。
5. 彻底终止发布构建，并为正常的先下载、后应用流程留出时间。
6. 关于原生日志、导出问题和配置检查，请使用当前调试指南：https://docs.expo.dev/eas-update/debug.md。

切勿仅为让更新显示出来而绕过兼容性或防变砖保护措施。

高级及相关工作流

• 切换渠道： 单个发布构建可以覆盖其 expo-channel-name 请求标头，以请求另一个兼容渠道。这与更改服务器端渠道到分支的映射不同。请遵循 https://docs.expo.dev/eas-update/channel-surfing.md，并遵守其中的访问控制、持久性、恢复和兼容性限制。
• 更新健康状况： 发布后，加载 eas-update-insights，监控采用率、启动失败、崩溃率、负载大小和发布情况。
• 应用商店发布： 当原生代码变更需要新的 TestFlight、App Store 或 Play Store 构建时，加载 eas-app-stores。

官方参考资料

• 设置：https://docs.expo.dev/eas-update/getting-started.md
• 概念与匹配：https://docs.expo.dev/eas-update/how-it-works.md
• 部署：https://docs.expo.dev/eas-update/deployment.md
• 调试：https://docs.expo.dev/eas-update/debug.md
• 当前 EAS CLI 参考：https://docs.expo.dev/eas/cli.md

提交反馈

如果你遇到错误、误导性信息或此技能中的过时信息，请报告，以便 Expo 改进：

npx --yes @expo/agent-cli@latest feedback --category skills --subject "eas-update" "<actionable feedback>"

只有在有具体且可执行的反馈时才提交。请尽可能提供相关背景信息。 如果 Agent 反复无法完成 Expo 任务，或用户不得不介入，请使用 --category evals 提交简要报告，说明任务、预期结果和问题所在，并将相关 Expo 软件包或命令作为 --subject。