App Store Connect API 4.5.1 截图接口怎么迁移？2026

Apple 将 App Screenshot Sets、App Screenshots、App Preview Sets、App Previews 标记为弃用；应用内活动的 App Event Screenshots 和 App Event Video Clips 也在迁移范围内。官方建议改用素材库图片、视频及 placements，但这条说明本身没有宣布旧资源立即停服。

先查代码仓库、流水线脚本和定时任务。不要只搜索接口路径，也要追踪资源 ID 在哪些步骤被保存、读取、排序或删除。旧集合通常承载的不只是文件：它还关联版本本地化、设备展示目标和顺序。新模型把可复用媒体与页面位置分开，直接替换接口名容易漏掉这些关系。

迁移盘点表至少记录：

• 应用、版本与本地化标识；
• 旧资源类型、文件标识、媒体类型及展示目标；
• 截图或预览的显示顺序；
• 当前调用方、凭证权限、失败重试和删除逻辑；
• 资源是否也用于 Custom Product Page、实验页面或应用内活动。

Apple 将素材库定义为集中管理图片和视频的位置；素材上传后，再通过 placement 关联到具体商店页面。先阅读迁移至 App Asset Library 的官方说明和素材库 API 资源概览，再把现有数据关系整理成可核对的清单。

⚠️ 迁移期间不要批量清理旧记录。先确认新素材已处理、目标 placement 已建立，并查清一份素材是否被其他页面复用；旧路径还在服务时，提前删除会让回滚失去可用对象。

新的模型不是“一个旧截图集合换成一个新集合”。你上传或复用一份图片、视频后，需要建立 placement，明确素材类型、展示类别、目标页面和设备组。目标页面可以是版本本地化、Custom Product Page、本地化的应用内活动或产品页实验页面。具体关系可对照 Apple 的商店页面素材 placement 说明。

关键是保留旧集合背后的业务语义，而不是机械复制字段。比如，同一张图可以用于多个页面；但每个页面仍需分别确认语言、展示目标和排序。素材库资产被复用时，删除某个 placement 只会移除它在该页面的位置，不会自动删除其他页面的引用。替换素材也要重新建立 placement，并再次校验顺序。

这张表是映射起点，不是 API 字段的一对一转换表。具体 placement 类型、设备组及适用限制，应在请求时根据 Apple 返回的参考数据确认。

Mac CI 截图上传不能把 HTTP 成功响应当成整条链路通过。Apple 的素材上传流程文档将流程分为预留、上传、提交和处理验证；上传提交后，素材仍可能处于处理中或进入失败状态。placement 也有自己的状态，并且与所属页面的状态相关。

将流水线拆成以下独立步骤，每一步保存可用于重试和审计的证据：

1. 读取当前规格。 调用素材规格参考数据，获取此时有效的展示类别、尺寸、格式及限制。API 4.5.1 加入 iPhone Duo 展示类别；不要把展示组或尺寸硬编码成长期不变的常量。
2. 生成映射清单。 将每份图片或视频对应到媒体类别、目标页面、本地化及顺序。为旧资源 ID 和新素材 ID 建立对照记录，便于回滚与审计。
3. 预留并上传素材。 按 Apple 返回的上传操作发送文件分片；提交时核对文件大小和校验值。上传网址可能有时效，失败重试要依据当前预留状态处理。
4. 等待素材处理完成。 重新读取资源状态，区分上传已提交、处理完成和处理失败。若失败，保存错误信息并走重新预留或修复路径，不要直接创建页面关联。
5. 创建并排序 placement。 绑定正确的图片或视频、页面本地化和展示组；按组写入顺序，再读取 placement 列表确认实际排序。
6. 核验页面并留证。 在隔离应用或非生产发布路径检查商店页面实际展示，记录资源 ID、处理状态、placement ID、页面截图和核验结果。API 返回对象存在，不等于页面上的视觉结果已经正确。
7. 放量并保留回滚条件。 小范围切换后对照旧页面和新页面的素材关联、顺序与失败恢复结果。任一验收项不符，就暂停扩展并恢复旧调用路径；不要把未经验证的 API 响应当作放行凭据。

素材规格会随可用展示类型变化。Apple 明确提供参考数据接口供调用方发现有效规格；像 iPhone Duo 这样的新展示类别，更说明固定常量可能过时。应以素材规格参考数据文档和官方截图规格说明为依据，在运行时读取并验证，而不是根据旧设备列表推断。

活动媒体不能只按“图片”或“视频”分类。还要确认活动本地化、目标 placement，以及素材是否被其他活动或商店页面复用。活动旧资源已列入弃用范围，新流程应以素材库图片、视频和活动本地化 placement 组织。

重点防三个问题：把版本页面素材错连到活动页面；把视频当作图片创建 placement；为了替换一处展示而删除仍被其他页面使用的原素材。Apple 的 placement 关系允许一个素材用于多个位置，先查引用关系再删除，能避免误删共享资源。提交审核也要以页面所属状态为准，不能仅凭素材自身状态判断活动已可展示。

弃用清单里具体有哪些旧截图和预览资源？
重点排查 App Screenshot Sets、App Screenshots、App Preview Sets、App Previews，以及活动媒体的 App Event Screenshots、App Event Video Clips。它们被标记为弃用，意味着应规划新路径；不能据此断定旧接口已立即停止服务。

旧截图集合是不是直接改成 placement？
不是。旧集合用于组织截图或预览；新流程要先把媒体放入素材库，再创建 placement 指向具体页面。先从旧数据提取本地化、媒体类型、展示目标和顺序，再建立新关联。两个模型承载的信息不同，不能只替换资源名称。

活动图片和视频迁移后怎样防止误删？
建立素材 ID 到 placement ID 的引用清单，分别核对活动本地化和媒体类型。删除 placement 前检查它指向的页面；删除素材前检查是否仍被其他 placement 引用。替换时先创建并验收新素材，再调整页面关联，避免先删后补造成空白。

怎样判断上传结束且截图正确展示？
上传完成只代表文件已提交。继续读取素材处理状态，确认 placement 绑定正确的页面与展示组、排序符合预期，并到隔离应用页面实际核验。保存状态、资源 ID 和页面核验记录；如处理失败或页面错误，暂停放量并恢复旧路径。

截图由 Mac CI 生成，接口变化会要求重建节点吗？
通常不需要。把截图生成与 App Store Connect 媒体管理拆开：生成任务仍在现有环境执行，改动集中在新资源上传、处理状态检查和 placement 创建。只有截图工具链或其他流水线步骤本身依赖 macOS，才需要评估 Mac 节点；API 资源模型变化本身不是重建节点的理由。

• 若截图由现有 macOS 工具生成，或构建、签名步骤依赖 macOS：保留对应任务，单独迁移媒体 API 链路；验证新旧路径能分别运行，再决定是否调整节点。
• 若图片和视频已在其他环境生成，且 API 调用可在现有发布 Runner 执行：先迁移 API 调用和 placement 验收，不要仅因 4.5.1 采购或更换 Mac 节点。
• 若团队缺少稳定的 macOS 执行环境，但确有截图生成、构建或签名任务：先列明任务、权限、隔离和恢复要求，再比较自购主机与远程 Mac。需要固定物理接口或长期稳定重负载时，自购设备可能更合适；临时扩容或试运行则可评估按需租用。

执行放行前逐项勾选：

• [ ] 旧资源调用点、页面关系和删除逻辑已盘点。
• [ ] 图片、视频和 placement 类型与目标本地化匹配。
• [ ] 展示组及限制来自当前参考数据，而非长期硬编码。
• [ ] 上传、处理、placement、排序和页面展示分别有验收证据。
• [ ] 灰度失败可停止放量，旧路径仍可用于回退。
• [ ] 未把 API 成功响应误记为页面展示成功。

迁移资料应以 Apple 的发布说明、素材上传流程和商店素材管理文档为准。对照官方文档复核资源名称、处理状态和页面关系；实际展示结果仍应由你的测试应用验证。

如果现有方案依赖手工关联素材、把上传响应当作最终结果，或将截图生成与发布 API 紧耦合，迁移时就容易出现顺序错乱、状态误判和回滚困难。若团队确实需要 macOS 执行环境，可查看 CALMVPS 的远程 Mac 服务信息与套餐说明，再按任务周期和运维要求比较；若素材由其他环境生成，则先完成 API 迁移，无需为接口调整单独更换构建节点。