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 |
规则要点:
- 每次上传 ASC 的构建,CFBundleVersion 必须比该 App 曾上传过的任何 build 更大(字符串比较规则以 Apple 文档为准,实践上用工整数最稳)。
- CFBundleShortVersionString 在产品决定对外发布时变更;纯修 bug 可不变 marketing 版本,只增 build。
- 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 操作顺序(概念层)
- Xcode Archive → Upload(build 已在包内)。
- ASC 等待处理完成 → 测试员可见 / 可选入版本。
- 创建或选择 App Store Version(marketing)→ 选 Build。
- 填 更新说明 与审核备注。
菜单文案会变,以 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:
对外是否同一「版本故事」:是 / 否
客服口径(用户问版本时怎么说):
常见误区
- 只改 Xcode 显示版本,忘了 plist。 上传包仍是旧 build。
- marketing 跟着 build 每天变。 用户困惑,商店历史难读。
- 拒审后 marketing 从 1.2 跳到 2.0。 无产品意义的大跳。
- TestFlight 与提审各用不同 marketing 故事。 备注对不上。
- 多个 target 共用 bundle 但 build 不同步。 Watch / Extension 撞规则。
- 复用被拒构建的 build 号重新上传。 不允许。
- 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 必须同号吗?
不必。纪要里写清两端各自编号,避免客服混记。
下一步
- 在仓库写死「build 单调递增」规则并让 CI 执行。
- 下一次上传前填 iOS 发版纪要,与 App Store 材料清单 勾检。
- 计划 TestFlight 外部测试时读 TestFlight 外部测试 与 TestFlight 提审技巧。
- 拒审流程绑定 重修编号 模板与 拒审修复。
- 双端发版日用 双端对齐表 发客服。