App Store / Google Play · 清单验收 · 不承诺过审Telegram @hagee66

上架通

GOEE LISTING LEDGER

№ ZHgoee.cc
账号归你 · 邀请协作


2026-02-28

iOS 版本号与构建号规范:避免 TestFlight/提审混乱

CFBundleShortVersionString 与 CFBundleVersion 怎么递增;拒审重修与热修复场景编号策略。Telegram @hagee66。

官网传送门(可直接点击跳转)
打开本文 · 指南库 · 苹果上架 · 谷歌上架 · 双端上架
Telegram 询价 @hagee66 · 官网 goee.cc

App Store Connect 里「版本号」和「构建号」各管一件事:用户看到的 marketing 版本,与系统用来区分每一次上传的二进制标识。混用、倒序、复用旧 build,会导致 TestFlight 测试员装错包、提审选不到构建、拒审后「明明改了却换不掉」线上展示。本文给 iOS 与上架同学一套可复制的递增规则,并衔 TestFlight 提审技巧、更新说明写法(若指南库已收录)。Apple 对字段格式与上限的规定以官方当前文档为准。不承诺编号正确即可过审。上架通 goee.cc · Telegram @hagee66。

这篇要解决的问题

  • 只改 CFBundleShortVersionString,CFBundleVersion 没变,ASC 拒绝上传或测试员看不到新包。
  • 拒审后小改却升了对外版本号,用户以为大版本,What's New 与宣传文本对不上。
  • 同一 marketing 版本下积累了几十个 build,审核备注写「见 build 37」而对外只说 1.2.0。
  • 与 Android versionCode 发版日撞车,发布纪要混成一行,客服说不清用户装的是哪版。
  • Hotfix 紧急换手能力时不知道是否应该 bump marketing version。

谁应该读

  • iOS 研发:改 Info.plist / Xcode 项目设置、CI 自动 bump。
  • 上架执行:在 ASC 创建版本、选构建、填更新说明。
  • 产品 / 运营:版本名与用户沟通、与 分阶段发布(若已收录)对齐。
  • 客服:根据版本号判断是否已含某修复。

材料清单见 App Store 上架材料清单。

核心做法

两个字段分别是什么

字段 Info.plist 键 典型用途
营销版本号 CFBundleShortVersionString 用户可见,如 1.3.0
构建号 CFBundleVersion 每次上传唯一递增,如 87

规则要点:

  1. 每次上传 ASC 的构建,CFBundleVersion 必须比该 App 曾上传过的任何 build 更大(字符串比较规则以 Apple 文档为准,实践上用工整数最稳)。
  2. CFBundleShortVersionString 在产品决定对外发布时变更;纯修 bug 可不变 marketing 版本,只增 build。
  3. TestFlight 与 App Store 提审共用同一套 build;测试员看到的版本号组合应能映射到发布纪要。

推荐递增策略(团队可写进 README)

策略 A:线性 build(推荐中小团队)

  • Marketing:按语义化版本 MAJOR.MINOR.PATCH,产品发版会拍板。
  • Build:全局单调递增整数(CI 每次 +1),不重置。

策略 B:marketing 与 build 绑定(慎用)

  • 如 1.3.0 (10300)。可读性强,但一旦跳号容易乱;需严格脚本生成。

无论哪种,禁止:回退 build、重复使用已上传 build、在本地改 plist 却未进归档包。

场景剧本

场景 Marketing Build What's New
日常迭代 可升 minor +1 写用户可见功能
拒审修复(非对外大改) 通常不变 +1 避免写「重构整个 App」;见拒审修复指南
TF 外部测试 与计划提审一致或略前 每上传 +1 TF 说明写内部测试向
Hotfix 已上线版 PATCH +1 或不变(产品定) +1 诚实写修复点
并行开发分支 主干规则统一 各分支均不得撞 build 合并前由 release 负责人统一 bump

与 Android 发版并行时,在发布纪要里分两行写 iOS build 与 Android versionCode,不混在一个「版本 42」里。

ASC 操作顺序(概念层)

  1. Xcode Archive → Upload(build 已在包内)。
  2. ASC 等待处理完成 → 测试员可见 / 可选入版本。
  3. 创建或选择 App Store Version(marketing)→ 选 Build。
  4. 填 更新说明 与审核备注。

菜单文案会变,以 App Store Connect 当前界面为准。

CI 与人工边界

  • CI:agvtool 或脚本 bump build,标签打 build-87。
  • 人工:发版负责人批准 marketing 变更。
  • 禁止:多人本地各 bump 一次未提交,导致仓库 plist 与上传包不一致。

与 TestFlight、分阶段发布

  • 外部测试构建仍需要唯一 build;测试反馈要记「build 号 + 日期」。
  • 分阶段发布针对已审版本的用户推送比例,不替代 build 管理。见 分阶段发布策略 若已上线。

可复制模板

iOS 发版纪要

【iOS 发版纪要】
产品:
Marketing version:
Build(CFBundleVersion):
较上一上传 build:+N
相对用户变更(一句话):
分支 / tag:
上传 ASC 时间:
处理完成时间:
TestFlight 范围:内部 / 外部
App Store 提审:是 / 否
What's New 维护人:
审核备注是否更新:是 / 否
已知不包含:

拒审重修编号

【拒审重修】
拒审日期:
原 marketing / build:
重修 build(必增):
marketing 是否变更:否(默认)/ 是(理由)
用户可见 What's New 变更:无 / 有(附文)
审核备注追加段落(摘要):

双端对齐表

发版日:
iOS marketing / build:
Android versionName / versionCode:
对外是否同一「版本故事」:是 / 否
客服口径(用户问版本时怎么说):

常见误区

  1. 只改 Xcode 显示版本,忘了 plist。 上传包仍是旧 build。
  2. marketing 跟着 build 每天变。 用户困惑,商店历史难读。
  3. 拒审后 marketing 从 1.2 跳到 2.0。 无产品意义的大跳。
  4. TestFlight 与提审各用不同 marketing 故事。 备注对不上。
  5. 多个 target 共用 bundle 但 build 不同步。 Watch / Extension 撞规则。
  6. 复用被拒构建的 build 号重新上传。 不允许。
  7. What's New 写「全新版本」但 marketing 未变。 元数据风险,见 拒审修复。

问与答

build 可以用带点的字符串吗?
Apple 对格式有要求,以当前文档为准。团队内推荐纯整数 build,减少比较歧义。

同一 marketing 下最多多少个 build?
无必要担心上限前先担心管理混乱。超过 20 个应清理测试策略,不是继续堆。

已上架用户如何知道 hotfix build?
用户主要看 marketing;客服后台用 build 对齐崩溃。公开沟通用 PATCH 版本即可。

CI 与手工上传混用会撞 build 吗?
会。指定唯一「build 颁发源」(通常是 CI)。

Extension 的 build 要和主 App 一致吗?
应遵循 Apple 对 target 的要求,以官方与 Xcode 提示为准,发版前用 Archive 验证。

与 Android 必须同号吗?
不必。纪要里写清两端各自编号,避免客服混记。

下一步

  1. 在仓库写死「build 单调递增」规则并让 CI 执行。
  2. 下一次上传前填 iOS 发版纪要,与 App Store 材料清单 勾检。
  3. 计划 TestFlight 外部测试时读 TestFlight 外部测试 与 TestFlight 提审技巧。
  4. 拒审流程绑定 重修编号 模板与 拒审修复。
  5. 双端发版日用 双端对齐表 发客服。

相关阅读

返回 指南库 · 苹果上架 · Telegram @hagee66