fastlane precheckcheck_app_store_metadata详解在提交 App Store 审核前自动检查元数据避免被拒【免费下载链接】fastlane The easiest way to automate building and releasing your iOS and Android apps项目地址: https://gitcode.com/GitHub_Trending/fa/fastlaneApple 会因各种可避免的元数据问题拒审应用包含脏话、提到其他公司的商标、甚至提及 Apple 自家产品的 Bug。precheck是 fastlane 中的元数据预审员它通过 spaceship 从 App Store Connect 下载应用元数据再逐一运行一组社区驱动的审核规则把拒审风险在提交之前暴露出来。本文基于文档 check_app_store_metadata.md 展开结合precheck组件源码讲清楚它检查什么、有哪些规则与参数、如何用Precheckfile和deliver做长期配置以及底层RuleProcessor的判定机制。一、precheck 的定位与工作机制precheck是一个独立的 fastlane 组件位于 precheck同时也以 action 形式注册在主包中。入口实现见 check_app_store_metadata.rbclass CheckAppStoreMetadataAction Action def self.run(config) # 仅当未设置 :api_key_path 时才从 SharedValues 中取 :api_key两者是冲突选项 unless config[:api_key_path] config[:api_key] || Actions.lane_context[SharedValues::APP_STORE_CONNECT_API_KEY] end require precheck Precheck.config config return Precheck::Runner.new.run end def self.return_value return true if precheck passes, else, false end def self.return_type :bool end def self.is_supported?(platform) platform :ios end end从源码可以看到三个关键事实precheck只是别名precheck.rb 中PrecheckAction CheckAppStoreMetadataActiondescription直接写着 Alias for thecheck_app_store_metadataaction因此两个名字可以互换使用返回布尔值所有规则跑完后action 返回true/false存在:error级别失败时返回false并抛出 user error方便在 Fastfile 中做流程控制仅支持 iOSis_supported?限定平台为:ios。底层执行流程由 Precheck::Runner 完成整体调用链为Precheck.config.load_configuration_file(Precheck.precheckfile_name)—— 加载Precheckfile中保存的默认规则配置认证 App Store Connect优先使用 API Keyapi_key/api_key_path否则回退到 Apple ID 登录Spaceship::ConnectAPI.login多团队时通过team_id/team_name环境变量FASTLANE_ITC_TEAM_ID/FASTLANE_ITC_TEAM_NAME消歧ensure_app_exists!—— 通过Spaceship::ConnectAPI::App.find(Precheck.config[:app_identifier])确认应用存在找不到直接报错Could not find app with App Identifier ...取版本use_live为真时取 App Store 上的线上版本get_live_app_store_version否则取最新未提交版本get_latest_app_store_version调用 RuleProcessor.process_app_and_version 运行全部规则打印结果表格有失败时输出 Potential problems 表字段名 失败原因警告黄色、错误红色若存在:error级别失败执行UI.user_error!终止 fastlane否则仅提示 found one or more potential metadata problems, but this wont prevent fastlane from completing。二、内置规则清单precheck 到底检查什么文档 Features 一节列出的能力对应 Options.rules 中注册的 10 条规则rules/all.rb 会加载rules/目录下所有规则文件规则 key检查目标对应 Features 描述negative_apple_sentiment元数据中对 Apple 产品的负面表述暗示产品有 BugApple 产品 bug 提及curse_words可能引起反感的脏话/冒犯性词汇脏话检查器other_platforms提到其他平台如 Android、Chrome 等提及其他平台unreachable_urls元数据中 URL 是否可达URL 可达性检查placeholder_words占位符/测试性质的词占位符/测试词future_functionality宣称尚未实现的未来功能提及未来功能test_wordstest、demo 等测试词占位符/测试词free_stuff_iap免费内容却在 IAP 中收费文档未单列源码新增custom_text用户自定义的词表需传data:可自定义词表检查copyright_date版权年份缺失或在未来版权年份检查每条规则都是 Rule 的子类并区分两种检查项类型TextRule处理TextItemToCheck文本字段和URLRule处理URLItemToCheck链接字段。Rule#check_item会先做两层过滤——handle_item?类型匹配与item_field_supported?规则只支持特定字段例如copyright_date只检查:copyright字段——不匹配的项直接跳过返回nil保证每条规则只作用于自己关心的字段。几个有代表性的规则实现unreachable_urlsunreachable_urls_rule.rb用Addressable::URI解析 URL并去掉 fragment通过 Faraday 发 HEAD 请求follow_redirects中间件只有状态码为 200 才算通过否则记录HTTP status或unreachable: urlcopyright_datecopyright_date_rule.rb用正则/\b(?:19|20)\d{2}\b/提取年份缺失年份报missing copyright year年份大于当前年份报copyright year is in the futurecurse_wordscurse_words_rule.rb把元数据分词含去标点变体后做 SHA256 哈希与词库哈希集合 curse_word_hashes/en_us.txt 比对命中即报出具体词custom_textcustom_text_rule.rb这是唯一的需定制规则needs_customization?返回true必须传入data: [word1, word2]词表会被strip.downcase归一化若没传data该规则会被整体跳过并打印提示#{rule.key} excluded because no data was passed to it。三、precheck 检查哪些元数据字段RuleProcessor.generate_app_items_to_check / generate_version_items_to_check 把 App Store Connect 返回的数据扁平化为待检查项每项带有语言标签便于定位问题出在哪个地区应用级App Info字段item_name备注应用名称:app_name应用副标题:app_subtitle可选字段空值自动通过隐私政策文本tvOS:privacy_policy_text隐私政策 URL:privacy_policy_url可选字段内购名称/描述:in_app_purchase需开启include_in_app_purchases默认开启版本级Version字段item_name版权信息:copyright关键词:keywords描述:description新功能说明Release Notes:release_notes支持 URL:support_url营销 URL:marketing_url可选值得注意的实现细节每个字段都按语言locale生成独立检查项失败输出会带(locale)后缀例如description: (fr_FR)标记为is_optional的字段副标题、营销 URL 等如果值为空Rule#perform_check会直接判为passed不会误报未覆盖字段会被显式提示RuleProcessResult.items_not_checked收集没被任何规则处理过的项Runner 会打印Metadata fields not checked by any rule: ...提醒你有字段处于检查盲区IAP 检查目前仍走旧的 iTunes Connect 接口源码注释注明 As of 2020-09-04, this is the only non App Store Connect call in prechecks因此使用 App Store Connect API Key 登录时无法检查 IAP——Runner 会直接UI.user_error!要求关闭include_in_app_purchases或改用 Apple ID 登录。四、使用方法与完整参数基本用法文档 Usage 节原样保留# 检查 App Store Connect 中的应用元数据 fastlane precheck # 查看所有可用选项 fastlane action precheck在 Fastfile 中以 action 方式调用时可内联配置规则级别action 中的 example_codecheck_app_store_metadata( negative_apple_sentiment: [level: :skip], # 跳过 negative_apple_sentiment 规则 curse_words: [level: :warn] # 脏话检查失败时仅警告 ) # 或者直接用别名 precheck完整参数定义见 precheck/options.rb参数短选项 / 环境变量默认值说明app_identifier-a/PRECHECK_APP_IDENTIFIER取 Appfile 中的app_identifier应用的 bundle ID必填username-u/PRECHECK_USERNAME取 Appfile 中的apple_id/itunes_connect_idApple ID 用户名使用 API Key 时可不填api_keyPRECHECK_API_KEY/APP_STORE_CONNECT_API_KEY—App Store Connect API KeyHash 形式敏感项与username、api_key_path互斥api_key_pathPRECHECK_API_KEY_PATH/APP_STORE_CONNECT_API_KEY_PATH—API Key JSON 文件路径与username互斥team_id-b/PRECHECK_TEAM_ID取 Appfile 的itc_team_id多团队时指定团队 IDteam_name-l/PRECHECK_TEAM_NAME取 Appfile 的itc_team_name多团队时指定团队名platform-j/PRECHECK_PLATFORMios取值仅限ios、appletvos/tvos、osx源码有 verify 校验default_rule_level-r/PRECHECK_DEFAULT_RULE_LEVEL:error未单独配置的规则使用的默认级别include_in_app_purchases-i/PRECHECK_INCLUDE_IN_APP_PURCHASEStrue是否检查内购use_livePRECHECK_USE_LIVEfalse是否改为检查 App Store 上线版本而非最新待审版本五、规则级别warn / error / skip每条规则有三档级别定义在 rule.rb 的RULE_LEVELS:warn—— 命中时打印警告不中断 fastlane:error—— 命中时所有扫描结束后UI.user_error!阻止后续命令执行:skip—— 该规则整体跳过Runner 会打印Skipped: 规则 - 描述。RuleProcessor.process_rules 中的判定逻辑对应文档 You can decide if you want to warn about potential problems and continue or have fastlane show an error and stop 这一 Featurerule_config Precheck.config[rule.key] rule_level rule_config[:level].to_sym unless rule_config.nil? rule_level || Precheck.config[:default_rule_level].to_sym # 未配置则回落到默认级别 if rule_level RULE_LEVELS[:skip] skipped_rules rule next end # ... error_results add_new_result_to_rule_hash(...) if rule_level RULE_LEVELS[:error] warning_results add_new_result_to_rule_hash(...) if rule_level RULE_LEVELS[:warn]最终由 RuleProcessResult 汇总只要error_results非空should_trigger_user_error?Runner 就报错退出只有警告时则打印UI.important提示后继续全部通过且无盲区字段时输出绿色成功消息。测试用例 rule_processor_spec.rb 覆盖了各级别的组合行为。六、Precheckfile持久化默认规则配置由于你可能想手动触发precheck而不希望每次都写全所有参数文档推荐把默认配置存入Precheckfile。执行fastlane precheck init可生成配置文件典型内容文档 Example 节原文# 表示该规则不会检查你的元数据 negative_apple_sentiment(level: :skip) # 命中时警告潜在的元数据问题 curse_words(level: :warn) # 报错precheck 结束后阻止后续命令执行 unreachable_urls(level: :error) # 传入任意你想检查的词 custom_text(data: [chrome, webos], level: :warn)Precheckfile会在 Runner 启动第一行就被load_configuration_file加载之后命令行参数可覆盖其中的设置。规则默认值还可从 Appfile 读取Rule.default_value委托给CredentialsManager::AppfileConfig.try_fetch_value因此团队可以把词表配置集中管理。七、与 deliver 集成提交审核前自动预审文档强调precheck与deliver完全集成。在 deliver/runner.rb 的precheck_app方法中可以看到完整衔接# 确保通过 precheck 后再上传 def precheck_app return true unless options[:run_precheck_before_submit] # ... precheck_options { default_rule_level: options[:precheck_default_rule_level], include_in_app_purchases: options[:precheck_include_in_app_purchases], # api_key / api_key_path / username / platform 等透传 } # ... precheck_success Precheck::Runner.new.run # precheck 内部异常时捕获并提示可用 verbose 模式排查 end随后submit_for_review if options[:submit_for_review] precheck_success——只有 precheck 通过才会真正提交审核。相关 deliver 参数见 deliver/options.rbrun_precheck_before_submit默认开启可设为false关闭注意 deliver init 时会强制置为falseprecheck_default_rule_level—— 透传给 precheck 的默认规则级别precheck_include_in_app_purchases—— 透传 IAP 检查开关。因此 Fastfile 写法即文档 Example 节所示lane :production do # ... # 默认 deliver 会调用 precheck 并警告任何问题 # 若希望 precheck 失败时中止提交审核可传 precheck_default_rule_level: :error deliver(precheck_default_rule_level: :error) # ... end # 或者单独运行 precheck lane :check_metadata do precheck end八、给 precheck 补充规则文档最后一条建议如果发现新的常见拒审模式请到项目仓库提交 issue 并附上 App Store 拒审邮件内容注意脱敏因为 issue 是公开的。从源码结构看新增规则的成本很低继承TextRule或URLRule实现key、env_name、friendly_name、description、rule_block返回RuleReturn.new(validation_state:, failure_data:)必要时覆写supported_fields_symbol_set限定作用字段再把类加入 Options.rules 数组即可被 Runner 自动拾取。小结precheck别名check_app_store_metadata通过 spaceship 拉取 App Store Connect 元数据按 10 条内置规则逐字段检查返回值供 Fastfile 分支控制规则支持:warn/:error/:skip三档级别未配置时回落到default_rule_level默认:error用Precheckfile持久化规则级别与custom_text词表用deliver(run_precheck_before_submit:, precheck_default_rule_level:)把它接进发布流水线使用 App Store Connect API Key 时无法检查 IAPuse_live可切换为检查已上线版本platform仅支持ios/appletvos(tvos)/osx三类取值。【免费下载链接】fastlane The easiest way to automate building and releasing your iOS and Android apps项目地址: https://gitcode.com/GitHub_Trending/fa/fastlane创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考