【免费下载链接】App-Store-Connect-CLIFast, scriptable CLI for the App Store Connect API. Automate TestFlight, builds, submissions, signing, analytics, screenshots, subscriptions, and more项目地址https://gitcode.com/gh_mirrors/ap/App-Store-Connect-CLI点击查看免费下载导读本文围绕 App-Store-Connect-CLI 的设计文档 docs/design/xcode-version-structured-editor.md深入讲解asc xcode version view/edit/bump命令组从依赖 macOS agvtool、逐行改写 project.pbxproj升级为基于对象图解析 无损 xcconfig 扫描 原子写入的结构化版本编辑器。你将掌握新增的--target/--configuration作用域、--next-build-number远程安全构建号、结构化 JSON 变更输出以及底层实现原理与验证策略可直接在 CILinux/Windows/macOS上安全地自动管理 MARKETING_VERSION 与 CURRENT_PROJECT_VERSION。一、设计定位命令组保持原位能力原地升级本次改动不新增任何顶层命令也不修改命令注册表registry。所有能力仍然收敛在已有的asc xcode version命令组之下包含三个子命令view查看版本号、edit编辑版本号/构建号、bump递增版本号/构建号。从源码看命令组的入口定义在 internal/cli/xcode/xcode_version.go#L72-L110通过ffcli.Command注册xcodeVersionViewCommand()、xcodeVersionEditCommand()、xcodeVersionBumpCommand()三个子命令ShortHelp明确说明其职责是 Read and modify Xcode project version numbers。1.1 旧行为与痛点改动前的实现存在明确的平台与可靠性局限view、edit、bump均要求 macOS 环境且依赖 Apple Generic Versioning即agvtool。现代项目的解析读取依赖xcodebuild -showBuildSettings。现代项目的写入方式是逐行扫描project.pbxproj替换所有以MARKETING_VERSION 或CURRENT_PROJECT_VERSION 开头的行。由此带来的问题在文档中被逐一列出并可在旧代码路径中得到印证internal/xcode/version.go#L223-L278 的getVersionLegacy仍保留 agvtool 调用旧行为问题后果写入是 project-wide全项目生效无法只针对某个 target 或 configuration 精确修改依赖文本格式缩进、换行风格变化会导致误匹配或漏改无法处理 xcconfig 承载的构建设置xcconfig 中的版本号不会被更新以0600权限重写文件破坏原有文件权限位影响团队协作与源码管理二、公开命令形态新增作用域与远程构建号参数2.1 作用域参数--target/--configuration原有全部调用方式保持有效新增两个可选参数asc xcode version view \ [--target NAME] [--configuration NAME] asc xcode version edit \ [--version VER] [--build-number NUM] \ [--target NAME] [--configuration NAME] asc xcode version bump --type major|minor|patch|build \ [--target NAME] [--configuration NAME]作用域组合的语义非常明确三条规则即可完整覆盖两个都不给保留原有的 project-wide全项目编辑行为只给--target更新该 target 下的全部 configuration只给--configuration更新该项目及所有 target 中的该 configuration。在命令实现中--target与--configuration被定义为fs.String参数并传入GetVersionOptions/SetVersionOptions/BumpVersionOptions见 internal/cli/xcode/xcode_version.go#L141-L202。同时还有两个项目定位参数--project-dir默认.指向包含.xcodeproj的目录与--project当目录中存在多个.xcodeproj时指定具体项目路径selectedProjectInput函数在 internal/cli/xcode/xcode_version.go#L112-L120 中完成二选一逻辑底层findXcodeprojinternal/xcode/version.go#L744-L787在发现零个或多个.xcodeproj时会分别报错并提示使用--project消歧。2.2 远程安全构建号--next-build-number这是本次设计中最具 CI 价值的特性不再需要本地拼装 shell 管道去查询 App Store Connect 拿到下一个构建号。新增的无管道调用形态asc xcode version edit --next-build-number --app APP \ [--version VER] [--platform PLATFORM] [--initial-build-number N] asc xcode version bump --type build --next-build-number --app APP \ [--platform PLATFORM] [--initial-build-number N]约束规则文档原话 源码双重印证--next-build-number与--build-number互斥internal/cli/xcode/xcode_version.go#L272-L274 直接返回 usage error必须提供--app或环境变量ASC_APP_IDbump仅在接受--type build时允许携带该参数internal/cli/xcode/xcode_version.go#L398-L400未显式传入--version时本地的 marketing version 将作为远程版本过滤条件此时所有被选中的 configuration 必须解析出同一个marketing version否则命令会在发起 App Store Connect 查询之前就失败防止把不一致的版本号写进远程筛选。远程筛选相关参数与asc builds规范命令完全同义、同校验参数含义默认值--appApp Store Connect App ID、Bundle ID 或精确 App 名称也可用ASC_APP_ID空--platform远程构建平台过滤IOS、MAC_OS、TV_OS、VISION_OS空不过滤--processing-state远程处理状态过滤空--exclude-expired从远程筛选中排除过期构建false--initial-build-number远程尚无构建时的初始构建号1参数绑定实现在 internal/cli/xcode/xcode_version.go#L44-L53 的bindXcodeRemoteBuildNumberFlags且--initial-build-number在validateXcodeRemoteBuildNumberOptions中强制 1。解析流程复用asc builds next-build-number同源的 processed-build 与 in-flight-upload 逻辑resolveXcodeNextBuildNumber先经shared.NormalizeLatestBuildSelectionOptions归一化筛选条件再调用shared.ResolveNextBuildNumber定义于 internal/cli/shared/build_numbers.go#L84返回asc.BuildsNextBuildNumberResult中的nextBuildNumber见 internal/asc/output_builds.go#L57-L62。也就是说远程构建号的选择算法processed 构建优先、排除 in-flight 上传等与既有 builds 命令完全一致CI 脚本无需再自建幂等逻辑。2.3 交互与退出码契约设计文档明确了交互边界没有任何命令提示符no prompts数据始终输出到 stdout错误始终输出到 stderr用法错误返回退出码 2。这与仓库 cmd/exit_codes.go 中定义的 usage error 退出码约定保持一致便于脚本化调用方精确区分参数写错与业务失败。三、结构化输出JSON 向后兼容 变更明细JSON 输出保持向后兼容原有顶层 version/build 字段不变VersionInfo、SetVersionResult、BumpVersionResult、VersionChange等结构定义在 internal/xcode/version.go#L119-L202。变更mutation结果新增字段target与configuration仅在使用了作用域参数时出现omitemptychangedFiles稳定排序stable sorted的路径列表changes稳定顺序的变更明细数组每个元素包含setting设置名、oldValue、newValue、target、configuration、path以及source取值pbxproj或xcconfig。对应 Go 结构为 internal/xcode/version.go#L153-L173 的VersionChange{ setting: MARKETING_VERSION, oldValue: 1.2.3, newValue: 1.3.0, target: MyApp, configuration: Release, path: MyApp/Config/Release.xcconfig, source: xcconfig }view 结果在选中的值上附加来源路径。VersionInfo增加了target、configuration、versionSource、buildNumberSource与modern字段modern为 true 表示项目使用MARKETING_VERSION构建设置见 internal/xcode/version.go#L119-L129。Table 与 Markdown 输出保持原有 version/build 展示方式仅当作用域/来源信息存在时附加展示——命令实现中printVersionScopeAndSources在纯文本与 Markdown 两种渲染模式下分别以Target:/**Target:**形式打印作用域与来源internal/cli/xcode/xcode_version.go#L205-L220。四、实现原理三层纵深4.1 pbxproj对象图解析而非行扫描底层解析依赖github.com/bitrise-io/go-xcode/xcodeproject/xcodeproj。设计文档写的是v1.3.3MIT 许可而当前仓库go.mod中实际锁定版本为v1.3.4go.mod#L17版本略有前进但选型结论一致这是一个已在生产级 Go 工具链中广泛使用的结构化解析器。编辑器不再扫描文本行而是遍历 project 与 target 的 configuration list对象图。已存在的设置原位修改mutated in place不会在无关层级凭空捏造设置。对应实现是 internal/xcode/version_project.go#L32-L50 中的structuredVersionProject它持有xcodeproj.XcodeProj、pbxprojPath、配置列表configurations以及父子关系索引parentByChild并通过serialized.Object读取构建设置对象图。两个核心设置常量定义在 internal/xcode/version_project.go#L22-L25const ( marketingVersionSetting MARKETING_VERSION currentProjectSetting CURRENT_PROJECT_VERSION )4.2 xcconfig无损扫描器仓库自研了一个无损losslessxcconfig 扫描器能力清单与文档逐项对应处理赋值assignments、行注释//与块注释/* */兼容 CRLF 与 LF 行尾支持条件键conditional keys支持#include与#include?可选包含include 相对包含文件解析、环检测cycle-safe且可被多个 configuration 共享无关字节保持原样不动保留原有引号定界符编辑版本设置时与?被归一化为确保写入的 effective value 与请求值一致选中的 include 图内所有匹配的MARKETING_VERSION/CURRENT_PROJECT_VERSION变体都会被更新。实现证据在 internal/xcode/version_xcconfig.goparseXCConfigL95-L164逐行解析并维护块注释状态机xcconfigIncludePattern正则识别#include(?)?L15xcconfigAssignmentPattern正则识别、?、三种赋值符L14maskXCConfigCommentsStateL287-L339处理引号内注释豁免、//行注释与/* */块注释的遮蔽resolveXCConfigIncludeL348-L360解析 include 相对路径、自动补.xcconfig后缀并拒绝含未解析构建变量的 include。收集器collectXCConfigFiles系列L362 起以含文件预算maxFiles的图遍历方式收集源文件并在 Windows 大小写敏感目录等边界场景下保留正确的遍历身份语义。4.3 容错语义失败边界明确文档给出两条关键容错原则不可读的 xcconfig 图当所选作用域依赖它时才失败若坏图属于无关 configuration则不影响直接的 pbxproj view/edit。但当该坏图导致共享文件消费者shared-file consumer发现不确定时mutation 会保守地拒绝执行。读取解析本地解析直接 pbxproj 设置、已注册的 xcconfig 值以及简单的构建设置引用build-setting references包括跨下一层 target xcconfig 或 project 层的$(inherited)。target 的 xcconfig 继承以匹配的 project configuration 为种子与 Xcode 的层序一致。无法解析的构建系统变量产生显式错误而非臆造值调用方在需要 SDK 特定解析时应使用 Xcode。条件键conditional-only值可以编辑但不能作为 view 或 bump 的基线baseline因为缺少无条件值作为参照。仅定义了两种结构化设置中一种的项目以及仅把版本存在 Info.plist 的旧项目保留 macOS/agvtool 回退路径无作用域的远程构建号 bump 在该回退下仍可用——通过把解析出的数字传给agvtool new-version -all而有作用域的 legacy bump 会在任何 project-wide 写入之前被拒绝。Legacy 回退要求存在可发现、可解析、且缺少结构化设置的 Xcode 项目缺失、不可读、歧义的项目路径一律是 discovery error。4.4 原子写入与回滚这是保证多文件事务安全的核心每个输出文件在变更前完成 prepare 与 validate写入采用同目录临时文件保留原文件 mode解决旧实现 0600 权限问题fsync后 rename若后续某个文件失败已写入的文件会从其捕获的原始字节恢复提交前 staged pbxproj 会被重新解析reparse变更值若含注释语法或构建设置表达式在 staging 之前即被拒绝validateVersionMutationValue防止报告值与解析值分叉每个选中的叶 configuration 要么解析出请求值要么被安排一次实际 mutation未解析的受保护设置不能返回假成功。SetVersion/BumpVersion的入口internal/xcode/version.go#L281-L415先做validateVersionMutationValue校验再经openStructuredVersionProject打开对象图通过hasStructuredSettingsForMutation判定走结构化路径还是 legacy 回退ValidateSetVersion/ValidateBumpVersioninternal/xcode/version.go#L308-L466提供零写入的预检能力——bump --next-build-number在发起远程查询前正是先调用runValidateSetVersion/runValidateBumpVersion验证本地变更合法性见 internal/cli/xcode/xcode_version.go#L290-L299 与 L413-L425确保不会先改坏本地文件、再发现远程失败。4.5 xcodebuild 回退策略--xcodebuild-settings-lookup文档聚焦结构化解析仓库实现还额外提供了一个可控的隐藏回退开关--xcodebuild-settings-lookup auto|never默认auto。当结构化解析无法解析版本设置时auto策略会在 stderr 输出警告后运行xcodebuild -showBuildSettings兜底并把结果缓存在命令级BuildSettingsLookupSession中internal/xcode/version.go#L641-L715never则直接失败、不启动 xcodebuild对强制纯净环境的 CI 很有用。多 target 的-showBuildSettings输出会触发请使用--target的明确错误。五、兼容性与生命周期属于稳定命令的实现改进 附加 flag/JSON 字段不涉及破坏性变更既有的 project-wide 调用方式保持 project-wide 行为不变既有的人类可读输出保持可识别version/build 展示不变作用域/来源信息按需附加无需任何 deprecation 流程现代 pbxproj/xcconfig 操作变为跨平台Linux/Windows 也能改版本号仍需要 Xcode 构建系统解析或 legacy agvtool 行为的操作会以明确的 macOS/Xcode 要求报错requireMacOS/requireAgvtool见 internal/xcode/version.go#L596-L615。六、RED-GREEN 验证策略设计文档给出了完整的测试矩阵覆盖行为特征characterization与回归regression两层行为特征覆盖无作用域 flag 时的既有 project-wide 行为target-only、configuration-only、targetconfiguration 三种写入project 级与 target 级设置单个或多个递归 xcconfig include 的继承可选/缺失 include、include 环、共享 include、注释、引号值、赋值符、条件键、继承值、CRLF、无结尾换行、未变化字节区域。回归与错误路径覆盖畸形 pbxproj/xcconfig、缺失设置、歧义 target/configuration、多 application target、conditional-only 基线、部分迁移项目、不安全值、符号链接、权限、写失败、回滚、原子替换跨平台 view/edit/bump现代项目无需 agvtool远程 next-build-number 校验、API 错误、in-flight 上传、JSON 输出Xcode 26 与 Xcode 27 项目副本变更后用xcodebuild -list/-showBuildSettings重新解析校验全量门禁聚焦单元/CLI 测试 → 构建/tmp/asc黑盒检查 → format/docs/lint/test 全量流水线。仓库中的测试印证internal/cli/cmdtest/xcode_test.go断言edit与bump命令必须暴露--next-build-numberflaginternal/cli/cmdtest/xcode_test.go#L94-L118internal/xcode/version_xcconfig_test.go、version_xcconfig_containment_test.go、version_xcconfig_bench_test.go覆盖扫描器行为与性能version_structured_test.go覆盖对象图解析路径。七、为什么不用其他方案设计文档对候选方案做了取舍分析这是理解架构决策的关键候选方案被否原因保留行扫描编辑器实现更小但无法安全作用域化也无法理解 xcconfig 继承移植rork-xcode模型更丰富但会引入新的解析器维护负担调用 Fastlane 或 Ruby 的xcodeproj违反单二进制、无运行时依赖single-binary / no-runtime-dependency的项目契约Bitrisego-xcode解析器已在生产 Go 工具链中验证是最小的可信结构化底座仓库自有的 xcconfig 扫描与原子写入层恰好补足它缺失的行为八、实战速查查看当前版本与来源# 项目根目录内直接查看 asc xcode version view # 指定 target configuration并显示来源 asc xcode version view --target MyApp --configuration Release # 多项目目录中明确指定 .xcodeproj asc xcode version view --project ./MyApp/App.xcodeproj编辑版本/构建号结构化、跨平台# 全项目编辑 marketing version asc xcode version edit --version 1.3.0 # 仅编辑构建号不触碰版本号 asc xcode version edit --build-number 42 # 同时写版本与构建号 asc xcode version edit --version 1.3.0 --build-number 42 # 精确作用域只改 Widget target 的 Release configuration asc xcode version edit --target Widget --configuration Release --build-number 42 # 远程安全构建号本地版本作为筛选条件 asc xcode version edit --next-build-number --app com.example.app递增版本bump 类型映射major 1.2.3 → 2.0.0 minor 1.2.3 → 1.3.0 patch 1.2.3 → 1.2.4 build Increment CFBundleVersion (build number)asc xcode version bump --type patch asc xcode version bump --type minor --project-dir ./MyApp asc xcode version bump --type build --next-build-number --app com.example.app典型 CI 用法伪代码示意bump --type build --next-build-number --app $ASC_APP_ID一次性完成查询远程安全构建号 原子写入本地项目无需在 pipeline 中手写curl jq plutil组合若某一步失败远程 API 错误、本地校验失败、写入回滚命令以非零退出码终止且不留下半成品文件。结语asc xcode version的结构化升级本质上是把依赖 macOS 工具链的文本 hack替换为跨平台、可作用域、可回滚的结构化事务。对使用 App-Store-Connect-CLI 的发布自动化而言它让版本号管理具备了与asc builds等远程命令同等的可编程性参数即契约、JSON 即事实、原子写入即安全。想深入源码的读者可以从 internal/cli/xcode/xcode_version.go命令层、internal/xcode/version.go核心模型与 legacy 回退、internal/xcode/version_project.gopbxproj 对象图与 internal/xcode/version_xcconfig.go无损扫描器四个文件入手。赞分享【免费下载链接】App-Store-Connect-CLIFast, scriptable CLI for the App Store Connect API. Automate TestFlight, builds, submissions, signing, analytics, screenshots, subscriptions, and more项目地址https://gitcode.com/gh_mirrors/ap/App-Store-Connect-CLI点击查看免费下载相关推荐App Store Connect CLI 驱动 Xcode本地 build、archive、export 与 xcode test 结构化结果完整指南App Store Connect CLI 驱动 Xcode本地 build、archive、export 与 xcode test 结构化结果完整指南 ApApp-Store-Connect-CLI 工作流实战用 .asc/workflow.json 编排可复现的 Xcode→TestFlight 发布流水线App Store Connect CLI 工作流实战用 .asc/workflow.json 编排可复现的 Xcode→TestFlight 发布流水线 本App-Store-Connect-CLI 运行时迁移路线图Q2 2026 增量重写 asc 执行架构App Store Connect CLI 运行时迁移路线图Q2 2026 增量重写 asc 执行架构 本文解读 App Store Connect CLI上一篇终极视觉革命Photon光影包让Minecraft焕发电影级画面下一篇厦门大学论文LaTeX模板终极指南从零到一的学术排版自动化方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考