Back to Details

eas-update

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

EAS Update

EAS Update

EAS service - costs apply. EAS Update is available on the Free plan; publishing and delivery use update, bandwidth, and storage allowances, with higher limits on paid plans. See https://expo.dev/pricing.
Use EAS Update to deliver compatible JavaScript, styling, and asset changes to installed apps without submitting a new native binary. Native-code changes still require a new build.
EAS服务 - 需付费使用。 EAS Update在免费套餐中可用；发布与分发会消耗更新次数、带宽和存储配额，付费套餐拥有更高限额。详情请见https://expo.dev/pricing。
使用EAS Update可向已安装的应用推送兼容的JavaScript、样式和资源变更，无需提交新的原生二进制包。原生代码变更仍需重新构建应用。

Start with the supported configuration path

从受支持的配置流程开始

Before changing anything, inspect 
package.json
, the Expo app config, 
eas.json
if present, and whether 
ios/
or 
android/
are tracked. Use what you find when reviewing the CLI's changes:
  • Preserve existing dynamic or platform-specific app configuration.
  • If 
    eas.json
    exists, preserve its profiles and existing channel assignments. The CLI adds a channel matching the profile name only to build profiles that do not already have one.
  • If 
    eas.json
    is absent, do not create it by hand. The CLI may direct the user to run 
    eas build:configure
    separately.
  • With tracked native projects, expect the CLI to synchronize the platform's native Update configuration. Without them, expect Continuous Native Generation to apply the native configuration during a later build.
Detect the Expo SDK version before installing packages or interpreting version-specific behavior.
If 
expo-updates
is not installed, install the SDK-compatible version:
bash
npx expo install expo-updates
Configure from the project root:
bash
npx eas-cli@latest update:configure
Use 
eas update:configure
rather than manually inventing 
updates.url
, 
runtimeVersion
, native metadata, or build-profile channels. The command understands EAS project linking, Continuous Native Generation, and projects with committed native directories. Review and explain its resulting diff.
If the command cannot proceed because the project is not linked or the user has not authorized the required remote operation, stop after any independently valid package installation and explain what remains. Do not partially reproduce 
update:configure
by adding a runtime-version policy, config plugin, update URL, or channels by hand.
For dynamic app config, non-EAS builds, or a command that cannot complete automatically, follow the current setup documentation instead of guessing: https://docs.expo.dev/eas-update/getting-started.md.
在进行任何修改前，请检查
package.json
、Expo应用配置、（若存在的）
eas.json
，以及是否跟踪了
ios/
或
android/
目录。查看CLI的变更时，请保留现有配置：
  • 保留现有的动态或平台特定应用配置。
  • 若
    eas.json
    已存在，请保留其配置文件和现有的渠道分配。CLI仅会为尚未配置渠道的构建配置文件添加一个与配置文件名称匹配的渠道。
  • 若
    eas.json
    不存在，请不要手动创建。CLI可能会引导用户单独执行
    eas build:configure
    命令。
  • 对于已跟踪的原生项目，CLI会同步该平台的原生Update配置；若未跟踪原生项目，则会在后续构建过程中通过持续原生生成（Continuous Native Generation）应用原生配置。
在安装包或解读特定版本行为前，请先检测Expo SDK版本。
若未安装
expo-updates
，请安装与SDK版本兼容的版本：
bash
npx expo install expo-updates
从项目根目录执行配置命令：
bash
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。

Keep the model straight

理清核心模型

  • Build: the installed native app. It contains native code, an embedded update, a platform, a runtime version, and normally a channel fixed at build time.
  • Update: a published JavaScript bundle, assets, and metadata for one platform and runtime version.
  • Branch: an ordered stream of updates. Its newest compatible update is active.
  • Channel: a stable deployment target embedded in builds. On the server, it points to a branch.
  • Runtime version: the compatibility boundary between an update and the native code in a build.
A build receives an update only when platform and runtime version match and the build's channel points to the branch containing that update:
text
installed build (channel: production, runtime: 1.1.1, platform: ios)
  -> production channel
  -> production branch
  -> newest update for runtime 1.1.1 and ios
Channels and branches commonly have the same name, but they are separate objects. 
eas channel:edit
changes a channel's server-side branch mapping for every build on that channel. It does not change an individual installation's embedded channel.
Use this model to make decisions, but explain only the concepts needed for the user's request rather than reciting the entire model every time.
  • 构建（Build）：已安装的原生应用，包含原生代码、嵌入的更新包、平台信息、运行时版本，通常在构建时固定渠道。
  • 更新（Update）：针对单一平台和运行时版本发布的JavaScript包、资源及元数据。
  • 分支（Branch）：有序的更新流，其最新的兼容更新为当前活跃更新。
  • 渠道（Channel）：嵌入在构建中的稳定部署目标，在服务器端指向一个分支。
  • 运行时版本（Runtime version）：更新与构建中原生代码之间的兼容性边界。
只有当平台和运行时版本匹配，且构建的渠道指向包含该更新的分支时，构建才会接收更新：
text
已安装构建（渠道：production，运行时版本：1.1.1，平台：ios）
  -> production渠道
  -> production分支
  -> 适用于运行时版本1.1.1和ios平台的最新更新
渠道和分支通常同名，但它们是独立的对象。
eas channel:edit
命令会修改该渠道下所有构建的服务器端分支映射，但不会更改单个已安装应用中嵌入的渠道。
请基于此模型做决策，但仅解释用户请求所需的概念，无需每次都复述整个模型。

Decide whether an update is compatible

判断更新是否兼容

Use an update for changes to JavaScript, styling, and bundled assets that the installed native runtime already supports.
Create a new native build when a change adds or modifies native code or native configuration, including most native-library additions and SDK upgrades. Do not work around a runtime mismatch or imply that publishing can add native capabilities to an existing build. See https://docs.expo.dev/eas-update/runtime-versions.md.
Do not change the project's runtime-version policy as an incidental fix. Explain how the current policy affects compatibility; treat changing it as a separate decision because it changes which installed builds can receive future updates.
若变更内容为JavaScript、样式和打包资源，且已安装的原生运行时支持这些变更，则可使用更新。
若变更涉及添加或修改原生代码或原生配置（包括大多数原生库添加和SDK升级），则需创建新的原生构建。请勿规避运行时版本不匹配问题，也不要暗示发布更新可为现有构建添加原生功能。详情请见https://docs.expo.dev/eas-update/runtime-versions.md。
请勿将修改项目的运行时版本策略作为附带修复方案。请解释当前策略如何影响兼容性；修改该策略属于独立决策，因为它会改变哪些已安装构建可接收未来更新。

Publish deliberately

谨慎发布更新

Check the current CLI help before relying on remembered flags:
bash
npx eas-cli@latest update --help
For the common channel-based flow:
bash
npx eas-cli@latest update \
  --channel <channel> \
  --message "<message>" \
  --environment <environment>
SDK 55 and later require an EAS environment for publishing. Choose the environment intentionally so exported code receives the intended variables.
Publishing changes remote state and can affect installed applications. Before running it, establish the exact project, channel, environment, platforms, runtime version, and message. Publish to production only when the user has explicitly requested or approved it; if the authorization or target is ambiguous, stop before the command and ask. Do not infer a production destination solely from the current Git branch.
Prefer a preview or staging channel for validation. When promoting a tested update, use the documented deployment flow so production receives the same artifact where possible: https://docs.expo.dev/eas-update/deployment.md.
在依赖记忆中的命令参数前，请查看当前CLI帮助：
bash
npx eas-cli@latest update --help
对于常见的基于渠道的流程：
bash
npx eas-cli@latest update \
  --channel <channel> \
  --message "<message>" \
  --environment <environment>
SDK 55及更高版本发布更新时需要指定EAS环境。请有意选择环境，以便导出的代码获取预期的变量。
发布更新会更改远程状态，并可能影响已安装的应用。执行命令前，请确认项目、渠道、环境、平台、运行时版本和消息是否准确。仅当用户明确请求或批准时，才可发布到生产环境；若授权或目标不明确，请在执行命令前停止并询问。请勿仅根据当前Git分支推断生产环境目标。
优先选择预览或预发布渠道进行验证。如需推广已测试的更新，请遵循文档中的部署流程，尽可能让生产环境接收相同的产物：https://docs.expo.dev/eas-update/deployment.md。

Test according to the build type

根据构建类型进行测试

Development builds

开发构建

Preview updates with the development build's Extensions UI, the EAS dashboard, or Expo Orbit. A normal 
expo-dev-client
development build does not behave like a release build's automatic startup update flow.
可通过开发构建的Extensions UI、EAS控制台或Expo Orbit预览更新。普通的
expo-dev-client
开发构建的自动启动更新流程与发布版构建不同。

Preview, TestFlight, and production builds

预览版、TestFlight和生产版构建

Release builds normally prioritize startup speed. With the default launch behavior, the app may start its current embedded or cached update while downloading a newly published update in the background. The downloaded update is applied on a later restart.
For manual QA, fully terminate the app rather than backgrounding it, reopen it, allow the update time to download, and, if the change is not visible, fully terminate and reopen it once more. Describe this as up to two cold launches, not a TestFlight-specific ritual:
  1. One launch can discover and download the update.
  2. The following launch can run the downloaded update.
Do not automatically change 
fallbackToCacheTimeout
to avoid the second launch. Waiting at startup trades launch latency and reliability for faster update activation. If the app needs an intentional update UX, consider the 
expo-updates
APIs for checking, fetching, and presenting a non-blocking restart action. Use the 
expo-updates
API reference for the project's detected SDK version.
发布版构建通常优先考虑启动速度。在默认启动行为下，应用可能会先启动当前嵌入或缓存的更新，同时在后台下载新发布的更新。下载的更新会在下次重启时生效。
对于手动QA测试，请完全终止应用（而非后台运行），重新打开应用，等待更新下载完成；若变更未显示，请再次完全终止并重新打开应用。此流程称为最多两次冷启动，并非TestFlight专属操作：
  1. 第一次启动可发现并下载更新。
  2. 第二次启动可运行已下载的更新。
请勿自动修改
fallbackToCacheTimeout
以避免第二次启动。在启动时等待会以启动延迟和可靠性为代价，换取更快的更新激活。若应用需要自定义更新交互，请考虑使用
expo-updates
的API来检查、获取并展示非阻塞式重启操作。请使用与项目检测到的SDK版本对应的
expo-updates
API文档。

Debug a build that did not update

排查未更新的构建

Check these in order:
  1. Confirm the update was published to the intended EAS project, channel or branch, platform, and environment.
  2. Compare the installed build's platform and runtime version with the published update.
  3. Confirm the build actually contains the expected update URL and channel; app-config changes take effect only in a newly compiled build.
  4. Inspect the channel-to-branch mapping and the active update on that branch.
  5. Fully terminate the release build and allow for the normal download-then-apply lifecycle.
  6. Use the current debugging guide for native logs, export problems, and configuration checks: https://docs.expo.dev/eas-update/debug.md.
Never bypass a compatibility or anti-bricking safeguard merely to make an update appear.
请按以下顺序检查：
  1. 确认更新已发布到预期的EAS项目、渠道或分支、平台和环境。
  2. 对比已安装构建的平台和运行时版本与已发布更新的对应信息。
  3. 确认构建确实包含预期的更新URL和渠道；应用配置变更仅在新编译的构建中生效。
  4. 检查渠道到分支的映射，以及该分支上的活跃更新。
  5. 完全终止发布版构建，等待正常的下载-生效生命周期完成。
  6. 使用当前的排查指南检查原生日志、导出问题和配置：https://docs.expo.dev/eas-update/debug.md。
切勿为了让更新显示而绕过兼容性或防崩溃保护机制。

Advanced and adjacent workflows

高级及相关工作流

  • Channel surfing: an individual release build can override its 
    expo-channel-name
    request header to request another compatible channel. This differs from changing the server-side channel-to-branch mapping. Follow https://docs.expo.dev/eas-update/channel-surfing.md and preserve its access-control, persistence, recovery, and compatibility constraints.
  • Update health: load 
    eas-update-insights
    for adoption, launch failures, crash rate, payload size, and rollout monitoring after publishing.
  • Store releases: load 
    eas-app-stores
    when native changes require a new TestFlight, App Store, or Play Store build.

Official references

官方参考文档

Submitting Feedback

提交反馈

If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
bash
npx --yes submit-expo-feedback@latest --category skills --subject "eas-update" "<actionable feedback>"
Only submit when you have something specific and actionable to report. Include as much relevant context as possible. If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.
如果您遇到错误、误导性或过时的信息，请报告给Expo以帮助我们改进：
bash
npx --yes submit-expo-feedback@latest --category skills --subject "eas-update" "<actionable feedback>"
仅当您有具体且可操作的反馈时才提交。请尽可能提供相关上下文。 如果AI代理多次失败或用户不得不接管Expo任务，请加载expo-skill-feedback技能并遵循其评估流程，而非使用上述命令。