eas-update-insights

EAS Update 洞察

EAS 服务——需要付费。 洞察涵盖通过 EAS Update 发布的更新。EAS Update 是一款付费的 Expo Application Services 产品，提供免费额度。更新交付以及这些命令所用的数据会计入你的套餐 EAS Update 用量。请查看 https://expo.dev/pricing。

直接通过 CLI 查询已发布 EAS Update 的运行状况：启动次数、启动失败次数、崩溃率、独立用户数、载荷大小、每个渠道中嵌入式与 OTA 用户的比例，以及每个运行时版本中最受欢迎的更新。数据与 expo.dev 上更新详情页和渠道详情页所用的数据相同；这些命令会以人类可读和 JSON 格式在终端中显示数据。

何时使用此技能

当用户希望评估已发布 EAS Update 的运行状况或采用情况时使用此技能：例如崩溃率、安装次数、独立用户数、包大小，或某个渠道中嵌入式用户与 OTA 用户的比例。

示例提示：

• “最新更新表现如何？”
• “最新更新运行正常吗？”
• “新版本的崩溃情况比上一个版本更严重吗？”
• “有多少用户在使用最新更新，有多少用户使用嵌入式构建？”
• “目前 production 上最受欢迎的是哪个更新？”
• “我们的更新包有多大？”

也适用于：发布后的逐步推出监控和回归检测。

当用户需要查看单个用户的崩溃详情或设备级报告时，请勿使用此技能；此技能仅提供 EAS 汇总指标。

先决条件

• 已安装 eas-cli（npm install -g eas-cli）。
• 已登录：eas login。
• 对于 channel:insights：请在 Expo 项目目录中运行（该命令会从 app.json 解析项目 ID）。update:insights 只需登录。

命令一览

命令	用途
eas update:list	查找近期更新组、其 group ID 和分支名称
eas update:insights <groupId>	按平台统计启动次数、启动失败次数、崩溃率、独立用户数、载荷大小和每日明细
eas update:view <groupId> --insights	更新组详情 + 附加相同的指标
eas channel:insights --channel <name> --runtime-version <version>	某个渠道 + 运行时的嵌入式/OTA 用户数、最受欢迎的更新及累计指标

这些命令都支持 --json --non-interactive，以便进行程序化解析。

查找 ID

查询更新组的洞察前，需要先获取其 group ID。使用 eas update:list 并指定 --branch <name>（该分支上的更新）或 --all（所有分支上的更新）。以非交互方式运行时，务必传入 --json --non-interactive；如果未指定分支或 --all 标志，命令会提示选择分支：

# Latest group id across all branches
eas update:list --all --json --non-interactive | jq -r '.currentPage[0].group'

# Latest group id on a specific branch
eas update:list --branch production --json --non-interactive | jq -r '.currentPage[0].group'

JSON 响应包含一个 currentPage 数组，每个更新组对应一条记录（同一次发布的两个平台会合并为一条记录）：

{
  "currentPage": [
    {
      "branch": "production",
      "message": "\"Fix checkout crash\" (1 week ago by someone)",
      "runtimeVersion": "1.0.6",
      "group": "03d5dfcf-736c-475a-8730-af039c3f4d06",
      "platforms": "android, ios",
      "isRollBackToEmbedded": false
    }
  ]
}

条目还会包含 codeSigningKey 和 rolloutPercentage，但仅当该组使用了这些功能时才会包含（未定义的值会从 JSON 输出中省略）。

使用 --branch <name> 调用时，响应顶层还会包含 name（分支名称）和 id（分支 ID）。

eas update:insights <groupId>

显示单个更新组的启动次数、启动失败次数、崩溃率、独立用户数、启动资源数量和平均载荷大小，按平台（iOS、Android）细分，并附上启动次数和失败次数的每日明细。

基本用法

eas update:insights 03d5dfcf-736c-475a-8730-af039c3f4d06

标志

标志	描述
--days <N>	回溯 N 天。默认值：7。不能与 --start/--end 同时使用。
--start <iso-date> / --end <iso-date>	指定时间范围，例如 --start 2026-04-01 --end 2026-04-15。
--platform <ios|android>	筛选单个平台。省略则查看该组中的所有平台。
--json	机器可读输出。隐含 --non-interactive。
--non-interactive	编写脚本时必需。

JSON 输出结构

顶层包含 groupId、timespan（start、end、daysBack）和 platforms[]，其中每个平台都发布到的每个平台各有一项。每个平台条目包含 updateId、totals（uniqueUsers、installs、failedInstalls、crashRatePercent）、payload（launchAssetCount、averageUpdatePayloadBytes），以及表示 { date, installs, failedInstalls } 时间序列的 daily[]。

完整的架构和字段参考，请参阅 references/update-insights-schema.md。

用于健康状况评估的重要字段：

• platforms[].totals.crashRatePercent，计算方式为 failedInstalls / (installs + failedInstalls) * 100。没有安装时为零。
• platforms[].totals.installs 和 uniqueUsers 可反映采用情况。
• platforms[].daily 是时间序列，可用于发现失败次数突然激增。

错误

• Could not find any updates with group ID: "<id>" — 分组不存在，或你没有访问权限。
• Update group "<id>" has no ios update (available platforms: android) — 使用了 --platform ios，但该分组未发布到 iOS。
• EAS Update insights is not supported by this version of eas-cli. Please upgrade ... — 服务弃用了 CLI 所依赖的字段。运行 npm install -g eas-cli@latest。

eas update:view <groupId> --insights

在标准 update:view 输出中内联扩展相同的各平台洞察数据。

# Human-readable
eas update:view 03d5dfcf-... --insights
eas update:view 03d5dfcf-... --insights --days 30

# JSON: wrapped as { updates: [...], insights: {...} }
eas update:view 03d5dfcf-... --json --insights

不使用 --insights 时，update:view 的行为与之前完全相同——现有使用方的 JSON 结构不会改变。--days / --start / --end 标志仅在设置 --insights 时生效；单独传入这些标志会报错。

eas channel:insights --channel <name> --runtime-version <version>

按渠道显示使用嵌入式构建与 OTA 更新的用户数量，以及哪些更新带来了最多流量。必须在 Expo 项目目录中运行。

基本用法

eas channel:insights --channel production --runtime-version 1.0.6

标志

标志	描述
--channel <name>	必填。 渠道名称（例如 production、staging）。
--runtime-version <version>	必填。 与已发布的版本完全匹配。请在 update:list 中检查 runtimeVersion 值。
--days <N>	回溯 N 天。默认值：7。
--start / --end	显式指定时间范围，与 update:insights 类似。
--json / --non-interactive	以机器可读格式输出。

JSON 输出结构

顶层包含 channel、runtimeVersion、timespan、embeddedUpdateTotalUniqueUsers、otaTotalUniqueUsers、mostPopularUpdates[]（每项包含 rank、groupId、message、platform、totalUniqueUsers）、cumulativeMetricsAtLastTimestamp[]，以及带有 labels 和 datasets 的图表结构对象 uniqueUsersOverTime 和 cumulativeMetricsOverTime。

完整的架构和字段参考，请参阅 references/channel-insights-schema.md。

需要关注的字段：

• embeddedUpdateTotalUniqueUsers 是运行嵌入式（打包在二进制文件中）构建的用户数量。
• mostPopularUpdates[] 按 totalUniqueUsers 对更新进行排名。注意： 这是服务器返回的前 N 项；otaTotalUniqueUsers 是该列表的合计值，如果有超过前 N 项的更新处于活跃状态，可能会低估 OTA 覆盖人数。
• uniqueUsersOverTime 和 cumulativeMetricsOverTime 是用于绘图的每日数据序列。

错误

• Could not find channel with the name <name> — 名称拼写错误或账户不正确。
• 表格中显示 "No update launches recorded" / JSON 中的 mostPopularUpdates 为空 — 尚未在该渠道 + 运行时版本上启动任何 OTA 更新。通常表示该渠道仍仅提供嵌入式构建。

常见工作流

验证我刚发布的更新是否健康

# 1. Grab the latest publish on production
GROUP_ID=$(eas update:list --branch production --json --non-interactive \
  | jq -r '.currentPage[0].group')

# 2. Give it some adoption time (minutes to hours), then check crash rate
eas update:insights "$GROUP_ID" --json --non-interactive \
  | jq '.platforms[] | {platform, installs: .totals.installs, crashRate: .totals.crashRatePercent}'

比较各平台之间以及与之前版本的 crashRate；突然飙升或表现不对称（iOS 飙升而 Android 持平，或反之）就是需要调查的信号。

比较两个渠道的采用情况

for channel in production staging; do
  echo "--- $channel ---"
  eas channel:insights --channel "$channel" --runtime-version 1.0.6 --json --non-interactive \
    | jq '{
        channel,
        embedded: .embeddedUpdateTotalUniqueUsers,
        ota: .otaTotalUniqueUsers,
        topUpdate: .mostPopularUpdates[0]
      }'
done

检测过去 24 小时内的发布回归

eas update:insights "$GROUP_ID" --days 1 --json --non-interactive \
  | jq '.platforms[] | select(.totals.crashRatePercent > 1)'

汇总版本说明中的分组指标

eas update:view "$GROUP_ID" --insights --days 30

易读的分组详情，以及每个平台过去 30 天的发布和失败数据，适合粘贴到变更日志或事件回顾中。

输出提示

• 将 JSON 传递给 jq；载荷经过结构化处理，便于筛选。
• --json 会启用 --non-interactive，但同时传入这两个参数可明确表达意图，也便于编写脚本。
• daily[].date 中的日期是 UTC ISO 时间戳；易读表格会将其显示为 YYYY-MM-DD（UTC）。
• CLI 表格中的列名为“Launches” / “Crashes”，而 JSON 使用 installs / failedInstalls。字段相同，显示名称不同。

限制

• 跨平台的唯一用户数可能会重复统计在 iOS 和 Android 上运行同一发布版本的用户。渠道洞察中的 otaTotalUniqueUsers 也有相同的注意事项，它是对 mostPopularUpdates 求和的结果。
• 新发布版本在指标管道完成同步之前，短时间内可能显示为零。
• 安装量是下载量，而非启动量：installs / “Launches” 字段统计下载了清单和启动资源的用户。只有在用户下次检查更新时才会登记一次已确认的运行（通常最多延迟 24 小时，具体取决于应用的更新策略）。因此，指标会比实际情况略有滞后。
• 崩溃由客户端自行报告：failedInstalls / “Crashes” 统计安装或启动时发生错误，并在下次检查更新时报告的更新。不会触发更新请求的崩溃（例如进程在恢复前被终止）不会显示。

提交反馈

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

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

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