asc-metadata-sync

asc metadata 同步

使用此技能可使 App Store 元数据与 App Store Connect 保持同步。对于 app-info 和版本本地化字段，优先使用规范的 asc metadata 工作流。仅当用户明确需要 .strings 文件或旧版 fastlane 格式的元数据时，才使用较低层级的 asc localizations 和 asc migrate 命令。

当前规范工作流

1. 拉取规范元数据

asc metadata pull --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata"

如果应用有多条 app-info 记录，请先解析 app-info ID，并显式传入：

asc apps info list --app "APP_ID" --output table
asc metadata pull --app "APP_ID" --app-info "APP_INFO_ID" --version "1.2.3" --platform IOS --dir "./metadata"

2. 编辑本地文件

规范文件写入以下目录：

• metadata/app-info/<locale>.json 用于应用级字段：name、subtitle、privacyPolicyUrl、privacyChoicesUrl、privacyPolicyText
• metadata/version/<version>/<locale>.json 用于版本字段：description、keywords、marketingUrl、promotionalText、supportUrl、whatsNew

版权不是本地化字段。请使用以下命令管理：

asc versions update --version-id "VERSION_ID" --copyright "2026 Your Company"

3. 上传前验证

asc metadata validate --dir "./metadata" --output table

对于订阅应用，还需加入额外的使用条款 / EULA 启发式检查：

asc metadata validate --dir "./metadata" --subscription-app --output table

4. 预览并应用

先运行试运行：

asc metadata push --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --dry-run --output table

确认计划无误后再应用：

asc metadata push --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata"

如果用户希望使用名称中含有 apply 的命令形式来操作同一组规范文件，请使用 asc metadata apply：

asc metadata apply --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --dry-run
asc metadata apply --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata"

对于需要在变更前明确审批的审核产物工作流，请使用 asc 2.6.1 中引入的元数据审核命令：

asc metadata plan --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --review-dir ".asc/metadata/review"
asc metadata approve --review-dir ".asc/metadata/review" --all
asc metadata status --review-dir ".asc/metadata/review" --output table
asc metadata apply --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --review-dir ".asc/metadata/review" --confirm

如果用户希望在受保护的应用前生成选择性审批产物，请使用 asc metadata approve --key "version:1.2.3:en-US:whatsNew" 或 --scope app-info,version。版本范围的键包含 App Store 版本字符串。

App Clip 和预览内容传输

元数据拉取 / 推送默认针对本地化文本。请显式选择资源范围：

asc metadata pull --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --include localizations,app-clip,previews
asc metadata push --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --include localizations,app-clip,previews --dry-run
asc metadata push --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --include localizations,app-clip,previews --confirm

预览验证需要 ffprobe。替换 App Clip 标头时会先删除旧标头，且还需要 --allow-deletes；请明确授权此替换。 导出内容可能包含 HLS .m3u8 播放列表和 .preview.json 引用，而非原始视频。可以重用匹配的远程预览；对于未匹配的引用，需要提供原始视频，或在 --include 中排除 previews。将播放列表重命名为 .mp4 并不能使其可上传。直接使用 video-previews download 也会返回播放列表；单独下载时，请使用 .m3u8 输出路径。

有关可重复使用的媒体库内容、标头 / 搜索创意资源或本地化展示位，请参阅 资源库工作流。这些内容与 App Clip 标头图像及普通元数据文本是分开的。

仅关键词工作流

仅需更改版本本地化的 keywords 字段时，请使用此工作流：

asc metadata keywords diff --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata"
asc metadata keywords apply --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --confirm

导入关键词研究数据：

asc metadata keywords import --dir "./metadata" --version "1.2.3" --locale "en-US" --input "./keywords.csv"
asc metadata keywords sync --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata" --input "./keywords.csv"

快速更新字段

对于一次性的版本本地化编辑，请传入明确的版本选择器。如果已有版本 ID，请使用 --version-id 以确保更新确定无误；如果使用版本字符串，请使用 --version 和 --platform。

asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "en-US" --whats-new "Bug fixes and improvements"
asc apps info edit --app "APP_ID" --version "1.2.3" --platform IOS --locale "en-US" --description "Your app description here"
asc apps info edit --app "APP_ID" --version "1.2.3" --platform IOS --locale "en-US" --keywords "keyword1,keyword2,keyword3"
asc apps info edit --app "APP_ID" --version "1.2.3" --platform IOS --locale "en-US" --support-url "https://support.example.com"

对于 app-info 字段，优先使用创建后的设置命令：

asc app-setup info set --app "APP_ID" --primary-locale "en-US" --privacy-policy-url "https://example.com/privacy"
asc app-setup info set --app "APP_ID" --locale "en-US" --name "Your App Name" --subtitle "Your subtitle"

较低层级的本地化文件

仅当用户明确需要导入 / 导出文件而非规范 JSON 时，才使用 .strings 文件：

asc localizations list --version "VERSION_ID" --output table
asc localizations download --version "VERSION_ID" --path "./localizations"
asc localizations upload --version "VERSION_ID" --path "./localizations" --dry-run
asc localizations upload --version "VERSION_ID" --path "./localizations"

对于 app-info 本地化：

asc apps info list --app "APP_ID" --output table
asc localizations list --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --output table
asc localizations download --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations" --dry-run
asc localizations upload --app "APP_ID" --type app-info --app-info "APP_INFO_ID" --path "./app-info-localizations"

旧版 fastlane 元数据

仅用于现有的 fastlane 格式目录树：

asc migrate export --app "APP_ID" --version-id "VERSION_ID" --output-dir "./fastlane"
asc migrate validate --fastlane-dir "./fastlane"
asc migrate import --app "APP_ID" --version-id "VERSION_ID" --fastlane-dir "./fastlane" --dry-run
asc migrate import --app "APP_ID" --version-id "VERSION_ID" --fastlane-dir "./fastlane" --confirm

Deliverfile 中的 metadata_path 和 screenshots_path 值优先级最高，并且相对于 Deliverfile 解析。使用 --fastlane-dir "./fastlane" 时，请使用 metadata_path "./metadata"，而不是 "./fastlane/metadata"；后者会解析为 ./fastlane/fastlane/metadata。请修正 Deliverfile 中过时的值，或将其删除以使用约定的 metadata/ 和 screenshots/ 目录。

所选 Fastlane 目录之外的路径会导致失败，除非操作员通过 --allow-external-metadata 或 --allow-external-screenshots 明确信任这些路径。导入不可信内容时，请勿启用这些标志。

导入的 --dry-run 默认会盘点本地输入。添加 --check-remote 可在不写入的情况下比较远程商店资源；这需要身份验证，并且可能会下载已交付的媒体。如果导出的播放列表引用无法匹配，且原始视频不可用，请使用 --skip-previews。

请检查验证正文以及进程退出状态：asc migrate validate 可能会返回包含 valid: false 和非零 errorCount 的报告，但退出码为 0。已确认的导入可能会输出包含已完成阶段和失败详情的 status: "partial"，同时以非零状态码退出，因此标准输出非空并不代表成功。

字符数限制

字段	限制
名称	30
副标题	30
关键词	100 个逗号分隔字符
描述	4000
新功能	4000
推广文本	170

Agent 行为

• 除非用户明确要求 .strings 或 fastlane 元数据，否则从 asc metadata pull 开始。
• 进行远程写入前，始终运行 asc metadata validate。
• 如果命令支持 --dry-run，请先用它预览远程变更。
• 如果用户希望在应用变更前生成可持久保存的审核记录，请使用 asc metadata plan 和 approve/status。
• 对于快速编辑，始终传入 --version-id 或 --version 以及 --platform；不要依赖含糊的最新版本行为。
• 将 App 信息字段与版本字段分开处理。
• 人工核验时使用 --output table，自动化时使用 JSON。