企业官网建设流程全解析

1. 先画一张上架路线图：工具到底在管哪几段

上架这件事，第一次做的人多半会在工具链上绕圈子：Xcode 里点 Archive，弹出一堆签名选项；好不容易导出 ipa，上传又卡在进度条上；等构建出现在 App Store Connect，还要面对元数据、隐私清单、审核备注和一堆状态字段。标题说的是“苹果 App Store 上架工具介绍”，但我更想聊的是这些工具各自管哪一段路，以及在什么团队规模下该用哪一档。读完你至少能判断三件事：小团队该不该上自动化、命令行上传怎么配、哪些报错是工具问题哪些是自己的工程问题。

先把结论摆前面：上架从来不是“一个工具”能搞定的事，它是一条由构建、签名、打包、上传、元数据、审核六个环节串起来的流水线。苹果官方给的工具覆盖了其中大部分节点，第三方工具则主要补两件事——把重复操作脚本化，以及把证书和元数据集中管理。你不需要一开始就把整套自动化搭起来，但你需要知道每个环节的“官方入口”在哪，否则出了问题连日志都找不到。

1.1 从代码到审核通过，中间其实有六道关

第一关是构建。Xcode 的 Archive 会把你的工程编译成一份带符号表的归档文件，扩展名是.xcarchive。这一步的坑主要在编译配置：Release 的优化等级、Swift 编译模式、是否剥离符号、是否开启 bitcode（这个选项在新版本 Xcode 里已经不再作为提交项）。很多人以为 Archive 成功就等于没问题，实际上签名校验、资源冲突、架构缺失都可能在这一步埋雷。

第二关是签名与导出。归档文件本身不能直接上传，你要用exportArchive把它转成 ipa，同时决定用哪种分发方式：App Store、Ad Hoc、Development、Enterprise。分发方式不同，描述文件（Provisioning Profile）和证书的搭配也不同。这一步最典型的翻车是“证书里包含的设备 UDID 对不上”或者“描述文件过期了但 Xcode 缓存还留着旧的”。

第三关是上传。ipa 要被送到苹果的接收端，走的是 HTTPS 分卷上传。官方现在主推两条路：图形界面的 Transporter，以及命令行工具iTMSTransporter。老一点的教程里会写xcrun altool --upload-app，这条命令在 2023 年 11 月之后已经不能用于向 App Store Connect 上传二进制了，继续照着抄会得到一个明确的停用提示。

第四关是构建处理。上传成功不代表马上能提审，构建会先进入“处理中”状态，系统要做符号表剥离、加密合规检查、隐私清单扫描。这个阶段短则几分钟，长则半小时以上，报错通常以邮件形式发到账号邮箱，App Store Connect 页面上只显示一个红点。

第五关是元数据。应用名称、副标题、描述、关键词、截图、预览视频、年龄分级、类别、隐私政策链接、支持链接，这些都在 App Store Connect 里填。截图尺寸要求会随设备更新，按当前后台提示的尺寸准备就行，别拿三年前的模板硬套。

第六关是提审与发布。提审时要选构建、填审核备注、提供演示账号，涉及内购的还要把内购项目和主应用一起提交。审核通过后可以选择手动发布、自动发布，或者开启分阶段发布。

1.2 选工具前先问三个问题

第一个问题是发布频率。一个月发一次版本，手动点一点完全够用，强行上自动化反而增加维护成本。一周发两三次，或者要做灰度、要做多环境包，那就值得把构建和上传脚本化，否则光改版本号就能改出事故。

第二个问题是团队里有几台 Mac。iOS 构建强依赖 macOS 环境，这是绕不开的硬约束。没有常驻 Mac 的小团队，用云端 CI 的 macOS 执行机更划算；已经有 Mac mini 或 Mac Studio 的，自建流水线的边际成本更低，但要想清楚机器由谁维护、Xcode 升级谁负责。

第三个问题是证书归谁管。个人开发者用 Xcode 自动签名最省事；团队协作就必须把证书和描述文件从“某个人的钥匙串”里拿出来集中管理，否则人一走、机器一换，整个发布链路就断了。这个问题的答案直接决定你要不要引入专门的证书管理工具。

2. 核心工具拆解：每一类解决什么问题

2.1 Xcode 与 xcodebuild：构建和归档的底座

Xcode 是图形界面，xcodebuild是同一套构建系统的命令行入口。两者不是替代关系，而是同一件事的两种触发方式。图形界面适合调参和排查，命令行适合放进脚本和流水线。真正要自动化，你最终一定会落到xcodebuild上。

归档命令的核心参数不多：-workspace指定工作区，-scheme指定方案，-configuration Release指定配置，-archivePath指定归档输出位置。如果工程用 Swift Package Manager 管理依赖，解析依赖这一步会在构建时自动完成；如果用 CocoaPods，记得先跑一次安装，否则工作区文件可能是旧的。

xcodebuild \ -workspace MyApp.xcworkspace \ -scheme MyApp \ -configuration Release \ -destination 'generic/platform=iOS' \ -archivePath build/MyApp.xcarchive \ archive

这里有个细节值得说清楚：-destination写成generic/platform=iOS而不是具体机型，是为了让归档不绑定某一台设备的架构，避免导出时出现“缺少 arm64”之类的报错。另一个细节是构建号。CFBundleVersion在同一个版本号下必须严格递增，重复的构建号会被接收端直接拒掉。手动改容易忘，所以实际项目里通常用脚本自增，比如用agvtool或者直接改 plist：

agvtool new-version -all $(date +%Y%m%d%H%M)

用时间戳做构建号是个土办法但很稳，缺点是看不出第几次构建。更常见的做法是从 CI 的环境变量里取流水线序号，保证单调递增且可追溯。

归档完成后，.xcarchive里包含dSYMs目录，这些符号文件要留着，线上崩溃日志的符号化全靠它。很多人上传完就把归档删了，等收到崩溃报告才发现对不上符号，只能重新构建一次，白白浪费一轮时间。

2.2 Transporter 与命令行上传：二进制怎么进城

Transporter 是苹果提供的上传客户端，有图形界面，也有藏在应用包里的命令行工具。图形界面的好处是直观，拖进 ipa、点交付、看进度条；坏处是不能进脚本，且大文件上传时界面容易让人误以为卡死。

命令行方式更适合流水线，工具路径通常在/Applications/Transporter.app/Contents/itms/bin/iTMSTransporter。调用时要传账号、密码或专用密码，以及要上传的文件。用专用密码而不是账号主密码，是为了避免双因素认证把脚本卡住。更稳妥的做法是用 App Store Connect API 的密钥，把密钥文件路径传给上传工具，这样既不用把密码写进脚本，也方便按角色控制权限。

/Applications/Transporter.app/Contents/itms/bin/iTMSTransporter \ -m upload \ -assetFile build/ipa/MyApp.ipa \ -apiKey /path/to/AuthKey_ABC123XYZ.p8 \ -apiKeyIssuer 00000000-0000-0000-0000-000000000000

注意这里说的是“上传通道”，不是“上传成功”。命令返回成功只代表文件接收完毕，后面的处理是异步的。脚本里最好加一段轮询，查构建状态直到变成可提审，否则流水线显示绿灯、人却不知道构建有没有真的处理完。

提示：notarytool是给 macOS 应用做公证用的，和 iOS 应用上架不是一回事。搜教程时经常把这两个混在一起，看到notarytool就要确认一下对方讲的是不是 Mac 分发场景。

2.3 App Store Connect API：把“点页面”变成“调接口”

App Store Connect 的网页后台适合人操作，不适合机器操作。API 的价值在于把那些重复动作变成请求：创建版本、上传元数据、查询构建处理状态、提交审核、管理测试员。它不负责传二进制，但负责传二进制之后的一切。

接入需要三样东西：密钥 ID、签发者 ID、私钥文件。私钥只能下载一次，丢了就得重新生成，所以团队里要有个固定的存放位置，而不是散落在个人下载目录。权限方面，密钥绑定的角色决定它能做什么，只做上传的密钥不要给管理员权限，这是最基本的最小权限原则。

API 的典型用法是配合脚本做元数据同步。比如把多语言描述放在仓库里，发布时用脚本推送到对应语言的市场。这样文案改动可以走代码评审，而不是靠人在后台手填。手填最大的问题是不可追溯，谁在什么时候改了哪句话，页面上看不出来。

2.4 Fastlane 这类自动化框架：值不值得引入

Fastlane 是一套用 Ruby 写的发布自动化工具集，把构建、签名、截图、上传、元数据管理拆成一个个 action，再用Fastfile串起来。它的优势不是“能自动化”，而是“把苹果那套零散命令封装成了可读的配置”。

lane :release do increment_build_number build_app( scheme: "MyApp", export_method: "app-store", output_directory: "build/ipa" ) upload_to_app_store( skip_metadata: true, skip_screenshots: true, submit_for_review: false ) end

这段配置的意思是：自增构建号、打 App Store 包、上传但先不提审。先上传再人工确认提审，是我比较推荐的做法，原因是提审会触发审核流程，一旦提交就不好撤回，留一道人工闸门能避免把测试包误提上去。

Fastlane 里有两个能力特别值钱。一个是match，把证书和描述文件加密存到私有仓库，团队成员按需拉取，解决“证书只存在某个人电脑里”的问题。另一个是snapshot，用 UI 测试自动截多语言多机型的图，省掉手工截图这件极其枯燥的事。

它也有代价。Ruby 环境、依赖版本、和 Xcode 新版本的兼容性，都需要有人跟。小团队如果只是偶尔发版，引入 Fastlane 的学习成本可能高于收益；一旦发布频率上来，这点投入很快就能回本。

2.5 CI/CD 平台：云端 Mac 还是自建机器

云端 CI 的好处是省去机器维护，Xcode 版本由平台方跟进，扩容按需。缺点是构建时长按分钟计费、调试环境不如本地直观、缓存策略要重新设计。自建机器的好处是环境完全可控、可以挂本地缓存、大工程增量构建快；缺点是要有人管系统更新、磁盘清理、Xcode 升级，还要考虑机器断电了怎么办。

选择时可以看一个很实在的指标：单次完整构建加打包的耗时。如果超过二十分钟，按次计费的云端方案成本会很快堆起来，这时候自建一台常驻 Mac 更划算；如果十分钟以内，云端方案的弹性优势更明显。

2.6 证书与描述文件管理：最容易被低估的一环

证书分开发证书和分发证书，描述文件分开发、Ad Hoc、App Store、企业四类。上架用的是分发证书加 App Store 描述文件。听起来简单，实际翻车大多出在这里：证书被撤销、描述文件过期、同一个 Bundle ID 下有多套签名配置互相覆盖。

Xcode 的自动签名能解决大部分个人开发场景，它会自动创建和管理证书。但自动签名在团队协作里容易失控，因为每台机器都可能生成新证书，而分发证书有数量上限。手动管理的思路是：分发证书只保留一到两张，私钥导出后加密存放；描述文件按环境生成，命名带环境和过期时间；所有这些东西进版本库时加密，出库时解密。

怎么判断该不该上证书管理工具？一个简单的信号是：团队里是否出现过“只有某台电脑能打包”的情况。出现过，就说明证书已经绑死在个人环境上了，这是发布链路里最脆弱的单点。

3. 从零跑通一次上架：完整实操记录

3.1 构建前的检查清单

正式归档之前，有几项检查能省掉后面大量返工。第一项是版本号规则：CFBundleShortVersionString用三段式，比如 2.4.1，对外可见；CFBundleVersion是构建号，内部递增，可以多位。两者不要混用，也不要把构建号写成带字母的字符串，接收端对格式有要求。

第二项是签名配置。确认 Release 配置下用的是分发证书和 App Store 描述文件，而不是开发证书。曾经遇到过一次，Debug 和 Release 的签名配置被同步成了同一套，结果归档成功、导出失败，报错只说“签名无效”，排查了半天才发现是配置串了。

第三项是依赖与资源。检查图片资源有没有重复文件名、有没有缺失的 1x/2x/3x、有没有把测试用的占位图打进包。资源冲突在编译期不一定报错，但会在上传处理阶段被扫描出来。

第四项是权限描述。相机、相册、麦克风、定位、通讯录、追踪，只要用了相关能力，就必须在Info.plist里写清楚用途描述。描述文案不能写“需要此权限以正常使用”，这种模板话术在审核阶段容易被追问。写清楚具体用途，比如“用于拍摄头像并上传”，通过率会高很多。

第五项是出口合规。ITSAppUsesNonExemptEncryption这个键要按实际情况填。只用了系统提供的 HTTPS，通常属于豁免范围；自己实现了加密算法，就要准备相应的合规材料。这一项填错会卡在构建处理阶段。

3.2 归档与导出的具体命令

归档完成后，导出的关键是ExportOptions.plist。这个文件决定了导出方式、签名风格、是否上传符号表。手写一份比在 Xcode 里点选更可控，因为配置可以进版本库，谁打包都用同一份。

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>method</key> <string>app-store</string> <key>signingStyle</key> <string>manual</string> <key>uploadSymbols</key> <true/> <key>stripSwiftSymbols</key> <true/> </dict> </plist>

method填app-store表示导出用于上架的包；signingStyle选手动时，需要提前把证书和描述文件装好；uploadSymbols打开后，符号表会随包一起上传，线上崩溃日志才能自动符号化。

导出命令本身很短：

xcodebuild \ -exportArchive \ -archivePath build/MyApp.xcarchive \ -exportOptionsPlist ExportOptions.plist \ -exportPath build/ipa

导出成功后，目录里会有 ipa 和一份日志。日志里值得看的是签名链和架构信息，确认包含 arm64、没有混入模拟器架构。混入模拟器架构的包在上传时会被拒，报错通常会提到不支持的平台。

3.3 上传的两种方式与参数

图形界面方式适合第一次跑通流程：打开 Transporter，登录，把 ipa 拖进去，点交付，等进度条走完。它的价值在于错误提示比较直观，能直接看到是哪一项校验没过。

命令行方式适合重复执行。除了前面提到的iTMSTransporter，也可以用 App Store Connect API 的密钥方式调用。密钥文件是.p8格式，签发者 ID 和密钥 ID 在后台生成时能看到。参数写错最常见的表现是认证失败，而不是上传失败，所以看到 401 类的提示先检查密钥和角色，不要怀疑网络。

上传过程中有几个实操点。第一，ipa 体积大的时候不要中途断网重试太多次，容易留下不完整的接收记录，最稳妥的做法是等它自己超时再重来。第二，上传完成后不要立刻去后台刷新页面，构建处理有延迟，频繁刷新只会让自己焦虑。第三，构建处理失败的通知发到账号邮箱，记得把这个邮箱加到日常检查列表里。

3.4 元数据、截图和隐私清单

元数据里最容易被低估的是截图。不同尺寸的设备需要不同分辨率的图，后台会明确列出当前要求的尺寸组合。手工截图的麻烦在于多语言：每种支持的语言最好都有对应截图，否则某些市场展示效果会很差。这也是自动化截图工具存在的理由。

隐私清单是近两年新增的要求。应用如果使用了某些被列为“必要理由”的接口，需要在工程里放一份PrivacyInfo.xcprivacy文件，说明用途。这不是可选项，缺失会在上传处理阶段被标记。实际做法是把这个文件加进主 Target 的资源里，并随每次发版检查内容是否与实际调用的接口一致。

隐私政策链接也是必填项。链接要能公开访问，不能是内网地址，也不能是空页面。审核人员会点开看，页面打不开是很常见的拒审理由。

3.5 提审与 TestFlight 分发

提审前建议先走一遍 TestFlight。内部测试的构建不需要完整审核，适合做冒烟测试；外部测试需要经过一轮 beta 审核，适合给真实用户试用。TestFlight 的构建有有效期，过期后测试员就装不上了，所以长期测试要记得定期传新构建。

正式提审时，审核备注要写清楚三件事：应用是做什么的、怎么触发核心功能、有没有需要特殊说明的配置。如果应用需要登录，必须提供可用的演示账号，账号不能过期、不能需要短信验证码。这一条看起来简单，但因为演示账号失效被拒的比例相当高。

提审后状态会经历“等待审核”“审核中”“待发布”几个阶段。审核时长没有固定值，不要拿别人的经验当承诺。通过后如果选的是手动发布，记得去点发布，否则应用会一直挂在待发布状态。

4. 常见问题与排查实录

4.1 上传阶段的报错

上传阶段的报错有个共同特点：提示信息很短，真正的原因藏在细节里。比如提示构建号重复，往往是因为 CI 缓存了旧的 plist，自增脚本没生效；提示签名无效，多半是描述文件和证书不匹配，或者本机钥匙串里有两张同名证书。

还有一类报错和处理阶段有关，比如提示某个接口缺少隐私清单说明。这种问题在上传时不一定立刻出现，等构建进入处理中才发邮件通知。排查方法是看邮件里给出的具体接口名，回到工程里搜索对应的调用位置，补上声明后重新传一个构建号。

4.2 审核阶段的被拒

审核被拒的理由集中在几类。功能不完整是最常见的一类，比如应用打开就是空白页、按钮点了没反应、需要登录但不给演示账号。这类问题在自己机器上很难发现，因为测试环境往往是通的，正式包却指向了测试地址。

隐私相关是另一大类。收集了设备标识却没有说明用途、申请了权限却没有对应功能、隐私政策里写的和实际收集的不一致，都会被追问。处理方式是逐项对照实际行为，把用不到的权限直接删掉，而不是补一段模糊的描述糊弄过去。

内购相关问题也值得单独提。虚拟商品必须走内购，这是硬规则；内购项目要和主应用一起提交；恢复购买的功能要有入口。这几条每年都有大量应用栽在上面。

4.3 一张速查表

5. 几条踩过坑才愿意说的经验

5.1 版本号和构建号别交给手写

手写版本号是发布流程里性价比最低的动作。人一定会忘，忘了就会重复，重复就要重新走一遍构建和上传。更麻烦的是，构建号重复的错误提示不会告诉你当前用的是哪个号，只能自己去翻 plist。

我的做法是把构建号完全交给 CI：流水线序号加时间戳组合，保证单调递增且全局唯一。本地调试用固定号，打包脚本读取环境变量覆盖。这样本地和流水线互不干扰，也不会出现两个人同时打包撞号的情况。

版本号则走另一套规则：功能迭代升中位，修复升末位，大改升首位。版本号一旦对外发布就不能回退，因为用户设备上装的是更高版本时，低版本包无法覆盖安装，测试同学会以为包打错了。

5.2 隐私与合规要提前一个版本做

隐私清单、权限描述、账号删除入口这些东西，等到提审前才补，往往要重新走一轮构建。比较稳的节奏是在功能开发阶段就把对应的声明加上，代码评审时一起看。尤其是账号删除，只要应用支持注册，就必须提供删除入口，这个要求已经执行了挺长时间，但还是能看到漏掉的。

另一个提前量是出口合规。如果这一版新增了自定义加密逻辑，别等到上传才想起来填合规信息。提前和负责合规的同事确认，比在上传失败后临时找材料要省事得多。

5.3 权限和协作：别让一个人捏着全部证书

证书集中管理不只是为了安全，更是为了发布链路不断。我见过一种情况：分发证书只存在一台旧笔记本的钥匙串里，那台机器一坏，整个团队两个月没法发版。后来改成私钥加密存进私有仓库，配合证书管理工具按需拉取，才算把这个单点去掉。

权限方面，App Store Connect 的角色要按职责分配。负责上传的账号给开发或应用管理角色，负责财务的给财务角色，负责客服的给客服角色。API 密钥同理，一个用途一把密钥，出问题能快速定位是哪条链路，也方便随时吊销。

最后分享一个小技巧：把每次发版的构建号、提交哈希、上传时间、审核状态记一张简单的表，放在团队都能看到的地方。出问题时这张表能省掉大量“到底传的是哪个包”的争论。工具再多，也只是把动作变快；真正让发布稳定的，是这些看起来不起眼的记录习惯。