App Store Connect API 4.6：INSTALLS 报表停更怎么办？2026

定时任务按计划请求 INSTALLS，却没有拿到新文件，仪表盘还把空值画成了零。

最快处理：截至 2026 年 11 月 7 日，App Store Connect API 4.6 的变化意味着新的 INSTALLS 报表不再生成；先确认这是报表生命周期变化，而非 CI 故障。保留仍可下载的历史文件，停掉针对“新报告缺失”的无限重试，并且在 Apple 未确认替代口径前，不要把其他指标标成 INSTALLS。

适合维护 App Store Connect 报表下载任务、macOS CI 定时任务或发行数据看板的开发者与工程师。
如果你只需要搭建 Xcode 上传或构建流程，而不维护 INSTALLS 数据，这篇文章的重点可能与你无关。

App Store Connect API 4.6 INSTALLS 报表：先判断报告状态

Apple 在 2026 年 11 月 4 日发布了 App Store Connect API 4.6；本文依据 Apple API 4.6 发布说明及版本发布页核对停更信息。要点不是“所有报表 API 都不能用了”，而是新的 INSTALLS 报告不再生成，历史报告仍可下载。

新报告还会继续生成吗？不会继续生成新的 INSTALLS 报表。请求参数仍可在销售与趋势报告接口文档中看到，不等于 Apple 仍会为新的报告周期产出文件；接口参数允许值与报表实际生成状态是两件事。

判断时，先看三个容易混淆的地方：

请求目标。确认任务调用的是销售与趋势报告下载接口，检查 report type、子类型、频率、报告日期与版本，避免配置错误被误判为停更。
请求结果。区分认证失败、权限不足、网络错误、限流或请求格式错误，与请求成功但没有新报告内容。接口文档列出了不同响应状态，排查时不要把所有非文件结果都归入同一类。
报告生命周期。若任务要的是停更后的新周期，重复重试不会让新报表重新生成；只有旧日期报告读取失败，才应继续检查凭证、参数和下载链路。

这也意味着，定时任务收到“无新报告”时，不应直接把 macOS CI 主机、网络或密钥判定为故障。先用一个仍存在的历史周期验证下载路径，再根据 Apple 对报表状态的说明更新任务结果分类。

下载、看板和替代指标的决策对比

你要处理的情况	建议动作	判断评分
新周期没有 INSTALLS 文件	将其记录为“报表已停更／无新报告”，停止对此状态无限重试	高
需要回看停更前数据	请求已有历史周期，成功后保存原始文件及请求参数	高
看板把缺失报告显示为 0	增加独立的“无数据”状态，避免画出虚假的下降趋势	高
想用其他数据填补 INSTALLS	先核对定义、范围、时间窗口和隐私门槛；未验证前不要宣称等价	低

表格中的评分是处理方案对当前问题的适配度，不是 Apple 的服务等级。执行前还要核对销售与趋势报告可用性说明：Apple 的报告可用性与存储规则有期限说明，但具体历史文件是否存在，仍要按报告类型和日期实际确认。

仪表盘把缺报当成零时

停更后怎样处理仪表盘与历史趋势？把“没有报告”与“报告记录的安装量为零”拆成不同状态。缺失表示当前没有可用报告数据；零值则是报告明确给出的测量结果，两者含义不同，不能用同一个数值表示。

推荐把数据层至少拆成“已取得报告”“报告明确为零”“报告缺失或不可用”三类。图表遇到缺报时应显示断点或状态说明，下游环比、同比和告警也要跳过这段缺失区间，不能拿零去计算变化率。

注意：不要仅凭图表连续性填补停更后的空档。插值或复制最近一期数据会制造并不存在的测量结果；如业务确需估算，应另设字段、注明估算方法，且不要覆盖原始报表数据。

停更前的历史报告还能读取吗？Apple 的 API 4.6 说明保留历史报告下载，但这不代表所有历史日期永久可取。将已下载文件纳入团队自己的归档，并记录 vendor、报告周期、report type、子类型、版本、抓取时间和校验结果。Apple 的报告可用性文档列有报告保留规则。对于 INSTALLS 的具体历史边界，应以 API 4.6 说明和实际历史请求共同确认，不要把一般规则擅自扩大为永久保证。

不把相似名称的数据当成等价替代

其他安装相关数据能直接填补 INSTALLS 的空缺吗？不能仅凭“都与安装有关”就认定口径相同。你要先确认业务指标究竟是下载次数、完成安装次数、用户获取，还是某个渠道或地区的安装事件，再核对可用报告的定义与覆盖范围。

例如，Apple 的分析指标定义把下载指标和使用指标分别说明：下载相关字段与实际安装次数并非同一概念；使用数据还受用户选择分享等条件影响。App Store 安装与删除报告说明描述的是另一种报告，其范围、数据条件和历史起点都需要单独核对。它与销售和趋势中的 INSTALLS 报表名称相近，不构成可以无缝替换的证据。

另一个容易误用的候选是Platform App Installs：Apple 文档说明它覆盖特定分发渠道与平台范围，不能默认视作全球、全平台的 INSTALLS 替代。涉及第一年安装量等业务定义时，也要核对 Apple 的相关报告字段说明；名称含“安装”不代表统计对象和用途一致。

在完成验证前，建议保留原指标名称和原始数据，新增候选指标时另列字段，并在看板标注定义差异。这样业务方仍可比较趋势，但不会误以为断档前后数据来自同一口径。

macOS CI 定时任务适配清单

新周期没拿到报告，是否就是脚本故障？不一定。先用历史日期请求验证 API 凭证、权限、参数和文件解析，再把新周期无报告作为可识别的业务状态；不要把任务进程退出成功误解为 Apple 仍在生成新报表。

按下面的顺序修改并验收：

[ ] 核对任务请求。将运行日志中的接口、report type、子类型、频率与日期记录下来；确认任务确实请求了 INSTALLS，而不是其他报告或错误周期。
[ ] 划分结果类别。至少区分下载成功、预期的无新报告、认证或权限错误、网络或服务错误、数据解析错误；不要用一个“空文件”状态覆盖所有情况。
[ ] 收紧重试条件。只对可重试的网络或服务异常按团队策略重试；已确认的新报表不再生成时，记录状态并结束任务。
[ ] 修改仪表盘与告警。把无新报告显示为缺失状态，避免写入零值；相应更新下游计算和告警条件，避免每个调度周期都触发同一错误告警。
[ ] 建立历史归档。保存原始报告、请求元数据和任务日志，并对文件名、日期、版本与存储位置做可追溯记录；不要只保留转换后的汇总表。
[ ] 分别验证数据路径和异常处理。使用一份可下载的历史报告验证请求、读取和归档；再通过安全的测试条件验证无报告分支和告警行为。历史请求通过，只能证明历史读取路径可用，不能证明新报告仍会生成。

App Store Connect API 可以由服务器端程序调用，不要求 API 请求必须运行在 macOS 上；具体可用角色与报告访问权限应以 Apple 的API 入门和访问说明为准。若你的任务还包括 Xcode 构建、macOS 专属工具或必须在线的 Mac 执行节点，再评估运行环境是否需要 Mac；可以先看远程 Mac 环境与使用指南，并结合UDPMac 常见问题与服务说明评估调度、维护和访问方式，不要为了下载这份报表本身额外迁移 CI。

用验收记录收尾，而不是把“成功”写成“有新数据”

任务适配完成后，验收记录应分别回答：历史报告能否读取、缺报能否被识别、仪表盘是否保留空缺、重试与告警是否按预期结束，以及替代指标有没有经过口径审查。报告抓取任务成功，只说明程序按设计处理了当前结果，不代表 Apple 已恢复新 INSTALLS 报表生成。

复核日期是 2026 年 11 月 7 日；核对来源为 Apple 的 API 4.6 发布说明、销售与趋势报告接口文档及报告可用性说明。若 Apple 更新 API 4.6 说明、改变 INSTALLS 生成状态、宣布替代报告或调整历史下载规则，应重新检查任务逻辑。本文没有本站真实 CI 执行记录，因此不以本站实测补充报表可用性结论。

如果你当前的调度依赖本地电脑，睡眠或断网可能中断任务；如果依赖 Linux 节点，Xcode 等 macOS 专属工作仍需另找执行环境；自建 Mac 则要自行维护硬件和在线状态。对只需短期测试、临时归档或需要 Mac 专属工具的任务，租用 UDPMac 远程 Mac 可避免先购置一台专用机器，也便于将 Mac 任务与现有服务器分开管理；但长期稳定的高负载任务或需要本地物理接口时，自购设备可能更合适。最终选择应由你的 Mac 专属任务和运维责任决定，而不是由 INSTALLS API 请求本身决定。