最后更新于 2026 年 10 月 15 日；已核对 Apple 的 API 4.5.1 发布说明与相关素材管理文档。Apple 于 2026 年 10 月 6 日发布 App Store Connect API 4.5.1，并将旧截图、预览及应用内活动素材资源标记为弃用。症状 → 最快解法：代码依赖旧截图集或预览接口 → 新集成采用 App Asset Library；已有集成按素材类型迁移到资产与 placement 模型，并在每个 App 上验收上传、摆放和排序。弃用不等于接口已经停服，也没有据此给出迁移截止日。(developer.apple.com)
适合自动上传 App Store 截图或预览视频的独立开发者：核对旧接口与新资源模型的对应关系。 适合维护多个 App 或自定产品页素材的小团队：规划分批迁移并避免重复上传。 适合维护应用内活动媒体自动化的开发者：确认旧活动素材资源的替代方向。
迁移判断：按现有集成决定先后
先检查代码实际调用，而不是仅看依赖包版本。弃用是迁移信号，不是“现在开始就无法使用”的证据；在没有官方停服说明时，不要仅因版本发布就中断现有发布流程。新建集成直接围绕 App Asset Library 设计；已有自动化安排迁移窗口；尚未调用这些旧资源的系统，不需要为本次变更改写无关流程。
- 如果你正在新建素材上传流程：使用 App Asset Library images、videos 与 placements，不再按旧截图集结构设计新数据模型。
- 如果现有流程写入旧资源：按 App Store 版本截图与预览、自定产品页面、产品页实验、应用内活动分别盘点，选择一个可编辑的 App 先做迁移和验收。
- 如果只读旧素材或只维护未触及的功能：确认调用点和发布依赖，再决定是否把读取迁移与写入迁移放在同一批；不要把“暂不改动”误解成可以永远忽略弃用状态。
- 如果近期有素材发布：先冻结正在通过旧接口执行的变更范围，完成新旧记录对照和回滚准备，再按 App 分批切换，避免测试代码直接改动正在提交的线上素材。
资源模型：素材记录与展示位置分开
旧 set-based 模型通常从目标展示位置出发：先建立对应展示目标的素材集，再向集合上传截图或预览。新模型则先将文件作为 image 或 video 放入 App Asset Library，再创建 placement，指定它要出现在哪个页面本地化或活动位置。Apple 说明素材可以先独立上传，之后复用于符合条件的展示位置；placement 则将素材关联到具体目标。(developer.apple.com)
| 旧流程中的资源 | 新模型中的对应方式 | 迁移时重点检查 |
|---|---|---|
| App Screenshot Sets | placement 的展示类型与展示组 | 原来按设备区分的集合逻辑，改为读取展示组并创建位置关联 |
| App Screenshots | App Asset Library image 加 placement | 图片资产与页面上的截图位置分别追踪 |
| App Preview Sets、App Previews | App Asset Library video 加 placement | 视频处理、预览帧及目标本地化分别验收 |
| App Event Screenshots、App Event Video Clips | image 或 video 加应用内活动 placement | 目标切换到活动本地化，不能沿用产品页目标关联 |
| 自定产品页、产品页实验的旧素材资源 | image 或 video 加对应本地化 placement | 分别确认自定产品页和实验处理组的关系 |
接口覆盖：把读写与清理放进同一份盘点
先在仓库中搜索旧资源类型名、端点路径和内部封装方法，然后按素材使用场景登记所有调用。盘点要覆盖读、写和生命周期，而不仅是最容易发现的上传代码：
- 读取：获取旧集合、截图、预览及活动素材的逻辑，是否还被发布脚本或管理后台调用？
- 创建与上传：素材预约、分片上传、提交上传和后续状态轮询分别在哪里执行？
- 修改：预览帧、素材关联和目标本地化是否通过旧资源更新？
- 排序：当前顺序存放在集合关系、脚本配置还是数据库中？迁移后是否会按 placement group 重新设置？
- 删除与清理：删除集合时是否默认素材一并消失？清理脚本是否会尝试删除仍有关联位置的资产？
- 隐性成本：多个 App 共用一段脚本时，单个 App 的切换是否会改变其它 App 的素材 ID 映射？重试逻辑是否可能重复创建资源或漏掉 placement？
规格发现：在运行时读取展示能力
API 4.5.1 增加 List app asset library ref data，可用于读取支持的 placement 类型、展示组和素材规格。迁移时应从参考数据构建当前可用能力，而不是把设备枚举、像素尺寸或限制值复制进代码后永久不更新。特别是展示组可能随平台变化；硬编码会让上传流程在旧设备上看似正常，却在新增展示类别时漏掉适用目标。(developer.apple.com)
IPHONE_DUO 是 API 4.5.1 新增的展示类别之一。把它纳入能力发现，不等于任何现有截图都能用于这个展示位置：先读取参考数据中的 placement group 与屏幕尺寸，再检查返回的素材规格信息和上传处理结果。Apple 的截图规格页面列有 iPhone Duo 对应的尺寸，因此素材生成脚本应以官方规格资料和 API 返回数据为准，而不是从设备名称推断尺寸。([developer.apple.com](https://developer.apple.com/documentation/appstoreconnectapi/app-store-connect-api-4-5-1-release-notes?changes=l_1&utm_source=openai))
⚠️ **注意：**“API 接受上传请求”只说明请求进入流程；它不能证明文件已处理完成、能够关联目标位置、已在产品页显示或已经通过审核。将这些状态分开轮询、记录和告警，避免成功码被误当成发布完成。
落地执行：以单个 App 完成迁移闭环
以下步骤用于迁移已有集成，不是从 API 密钥开始的通用上传教程。Apple 的迁移说明建议将资产和位置作为独立资源处理；在进入批量切换前，用单个可编辑 App 验证映射与清理规则。(developer.apple.com)
- 确定迁移样本。选择一个可以编辑版本素材的 App，记录旧流程正在维护的本地化、展示目标、文件和顺序；先保存现状，作为切换前对照。
- 读取素材库与参考数据。获取该 App 的 asset library 关系，并查询
List app asset library ref data。按照所需目标筛选 placement 类型、展示组、尺寸和限制，保留响应快照供排错。 - 生成旧新映射。为每个旧素材记录文件校验信息、旧资源 ID、目标页面、本地化和显示顺序；把旧集合逐项映射成新资产与 placement，不要把一次上传等同于完成所有展示关联。
- 上传并等待处理。使用相应 image 或 video 创建流程上传素材，提交后重新读取资源状态。处理失败时先检查服务端返回的错误详情及文件规格，再决定重试；不要直接重复建资产掩盖失败原因。
- 创建目标 placement。对每个目标本地化和展示组关联对应资产。若同一张图用于多个页面，可复用资产 ID，但仍要分别创建并核对各处的 placement。
- 设置并读取顺序。使用 placement ordering 请求提交预期顺序，再读取目标本地化的 placement 关系进行比对。只看到资产列表顺序，不足以确认产品页上的截图排序。
- 按页面验收后再扩大范围。在 App Store Connect 中检查素材实际关联的页面、目标语言和展示顺序，并记录 API 响应与后台状态。通过样本后再把流程复制到其它 App；每个 App 仍要独立核对其素材和目标关系。
维护与删除：先解除位置关联
新旧模型的一个重要差异是，资产本体与页面位置不再是一条记录。上传一次后可以创建多个 placement，但映射表必须能够回答“这个素材 ID 在哪些本地化、哪些展示组中使用”。否则清理未使用素材时，可能误删仍在其它页面复用的资产。
清理逻辑也要随模型改变：先查询资产关联的 placements，移除不再需要的位置，再删除没有在用的资产。Apple 的迁移指引明确要求注意删除次序；如果原脚本仍沿用“删集合、随集合清除素材”的假设，就可能留下孤立记录，或因资产仍被引用而删除失败。(developer.apple.com)
视频和图片也要分开维护。预览视频可能涉及预览帧设置；Apple 的素材管理说明指出，已批准资产的 poster frame 不能再编辑，因此应在提交审核前完成画面选择与展示位置复核。对素材的修改需求如果发生在审核后，先确认状态允许的操作，不要把旧接口的修改行为直接套进新流程。(developer.apple.com)
端到端验收：从文件到页面展示分别留证
迁移验收要覆盖 API 与 App Store Connect 页面，而不是只看上传请求返回成功。建议每次测试记录输入文件标识、资产 ID、处理状态、placement ID、展示组、目标本地化、顺序和页面检查结果。
- 素材创建与处理：能读取新资产记录，处理状态达到可用于后续操作的状态；失败时保留具体错误信息。
- placement 关联：目标资源确实指向预期版本本地化、自定产品页、实验处理组或活动本地化；没有将素材误放到相似但不同的目标上。
- 顺序：读取排序请求涉及的 placement，与预期排列逐项对照；至少检查新增、调整和删除后的位置变化。
- 后台展示：在 App Store Connect 对应页面查看素材是否出现、顺序是否正确、页面是否选择了预期本地化。资产在库中不代表已进入页面。
- 审核状态：把素材处理、页面提交和审核结果分开记录。Apple 的素材状态说明区分上传、处理、提交审核及审核结果；不要把上传完成写成审核通过。(developer.apple.com)
- 回滚与重跑：保留切换前的目标和排序快照，定义重跑时是复用已有资产还是补建缺失 placement，避免脚本重试制造重复关联。
迁移评分：决定立即改、分批改还是暂缓
下面的评分是工程排期参考，不是 Apple 给出的风险等级。按条件选路线，并在迁移记录中说明依据：
- 若你正在开发新素材自动化，或当前代码需要新增旧接口调用：选用新模型。新写旧模型会增加后续改造工作，且与 4.5.1 指向的迁移方向相反。
- 若已有旧接口写入生产素材，且近期没有冻结发布的限制：分 App 迁移。先迁一个可编辑样本，验证素材处理、多个 placement、排序和清理，再推广到其它 App。
- 若系统只读取旧素材，或当前发布窗口不允许改动：暂缓切换，但立刻登记调用位置、依赖模块和后续复核负责人；暂缓不代表弃用状态消失。
- 若流程只替换上传端点，没有读取、排序和删除测试：不通过迁移验收。补齐关联读取、排序请求、删除次序与页面展示检查后再切换。
- 若需要从云端生成截图、运行脚本或持续执行发布自动化：单独评估 macOS 是否是你的实际执行环境需求。App Store Connect API 素材迁移本身不要求必须调用远程 Mac。
常见问题
旧截图接口弃用后，现有素材要全部重传吗？
不应仅凭弃用说明推断既有素材必须立即重传。先核实当前资源状态、自动化实际读写范围和未来页面变更需求；迁移目标是把后续维护转到资产与 placement 模型。若现有素材已可复用，按 API 返回的资源关系和页面检查结果决定是否需要补建资产或位置，而不是预先把所有文件重新上传。
一张图片如何用于多个语言页面？
在素材库中创建或找到同一张图片资产，然后针对每个目标本地化分别创建 placement。文件资产可以复用，但每个页面位置仍需要单独关联，并按各自展示组校验规格与顺序。不要把本地文件名相同或资产已存在，视为不同语言页面都已配置完成。
placement 排序与页面显示怎样核对？
先读取目标本地化及展示组下的 placements，再提交该组对应的排序请求，最后重新读取并对照页面中的实际显示顺序。保留排序前后记录，以便查出是请求未生效、关联目标错误，还是页面检查的本地化不一致。提交审核与审核结果还需分别记录，排序正确不代表审核通过。
选择执行环境：素材迁移之外再看 macOS 依赖
如果你目前的方案已经能在现有服务器上生成素材并调用 API，迁移 App Asset Library 不要求你为了接口本身改用 Mac。需要继续评估的是周边任务：截图是否要由 iOS 模拟器生成、构建和发布脚本是否依赖 Xcode，团队是否要让 macOS 工具链持续在线。非 Mac 环境的成本通常不是接口调用，而是模拟器与工具链缺失、执行环境维护分散，以及无法复现 Mac 专属步骤；这些缺点只在你的流程确实依赖它们时才构成迁移理由。
若这些任务需要真实 macOS 环境，自购 Mac 适合长期固定负载且需要本地物理接口的团队；短期迁移验证、临时生成素材或试运行发布脚本，则可以评估按需远程使用 Mac。你可先从 MACGPU 的远程 Mac 服务信息了解远程执行方式，再结合 Mac 配置选择信息判断是否适合你的脚本。租赁改善的是获取 macOS 执行环境的灵活性，不是调用 App Store Connect API 的前置条件；先按本地依赖作决定，再安排素材迁移。