asc-metadata-sync

asc metadata sync

使用此技能保持 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:en-US:whatsNew" 或 --scope app-info,version。

仅关键词工作流

仅在版本本地化 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"

字符限制

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

代理行为

• 除非用户明确要求 .strings 或 fastlane 元数据，否则从 asc metadata pull 开始。
• 在远程写入之前始终运行 asc metadata validate。
• 当命令支持时，使用 --dry-run 预览远程更改。
• 当用户希望在应用之前获得持久的审查工件时，使用 asc metadata plan 加 approve/status。
• 对于快速编辑，始终传递 --version-id 或 --version 加 --platform；不要依赖模糊的最新版本行为。
• 保持 app-info 字段和版本字段分离。
• 使用 --output table 进行人工验证，使用 JSON 进行自动化。