runner-images macOS 镜像 Toolset JSON 结构完全指南Xcode 与 Android 配置详解【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images本文基于 GitHub Actions runner-images 仓库中 images/macos/toolsets/Readme.md 展开深入讲解 macOS runner 镜像中 toolset JSON 的完整结构与配置语义并结合 Xcode.Installer.psm1、install-android-sdk.sh 等源码说明每个字段如何被真实消费。读完本文你将掌握如何编写、校验和扩展 toolset 文件从而控制镜像中安装的 Xcode 版本、模拟器 Runtime 以及 Android SDK 组件。Toolset 在 macOS 镜像中的角色toolset JSON 是 macOS runner 镜像生成流程的配置大脑。它被存放在 images/macos/toolsets/ 目录下以toolset-版本.json命名例如toolset-14.json、toolset-15.json、toolset-26.json。镜像构建脚本通过统一的入口读取它Common.Helpers.psm1 中的Get-ToolsetContent函数读取IMAGE_FOLDER环境变量指向的目录下的toolset.json并将其解析为 PowerShell 对象而 Bash 侧的脚本则通过get_toolset_value .xcode.versions...这类 jq 表达式按 JSON Path 取值。也就是说toolset 文件决定了镜像里装什么、装哪个版本、默认用哪个是镜像可复现性的核心保证。整个 macOS 镜像目录images/macos/按 OS 主版本划分 toolset 文件同一文件内部又按架构x64/arm64区分软件版本从而支持 Intel 与 Apple Silicon 两套并行配置。Xcode 配置详解Xcode 是 macOS 镜像中最重要的组件toolset 对它的描述也最细致。顶层结构如下xcode: { default: 16.4, x64: { versions: [ ... ] }, arm64: { versions: [ ... ] } }versions已安装 Xcode 版本清单versions是对象数组数组中每个对象描述一个将被安装的 Xcode 版本包含以下属性属性含义linkXcode 在镜像中的安装位置标识实际路径为/Applications/Xcode_link.appversion将被下载安装的 Xcode 版本号对应.xip安装包文件名symlinks需要为当前版本创建的别名符号链接列表sha256用于校验 Xcode 安装包完整性的 SHA-256 哈希install_runtimes控制模拟器 Runtime 的安装行为见下文filename下载文件名较新工具集中出现例如Xcode_26.3_Universal见 toolset-15.jsonlink与安装路径的对应关系在 Xcode.Helpers.psm1 中有直接实现Get-XcodeRootPath返回/Applications/Xcode_$Version.app。因此link: 15.4对应/Applications/Xcode_15.4.app。version 与 link 的命名规则version字段携带完整的版本与构建信息用或-分隔例如16.2.0-Beta.316C5023fBeta 版或16.2_Release_Candidate16C5031cRelease Candidate它会精确匹配.xip文件名。而link使用_代替空格例如16.2_Release_Candidate或16.1。原文档给出了 Apple 开发者站点下载 URL 的拼接模式DOWNLOAD_URLhttps://download.developer.apple.com/Developer_Tools/$SOURCE_FILE_LOCATION/$SOURCE_FILE_NAME.$FILE_EXTENSION SOURCE_FILE_NAMEXcode_$link SOURCE_FILE_LOCATIONXcode_$link FILE_EXTENSIONxip即link直接参与构建下载目录名与文件名。在实际镜像构建中Xcode.Installer.psm1 的Invoke-DownloadXcodeArchive通过${env:XCODE_INSTALL_STORAGE_URL}环境变量拼接Xcode-{Version}.xip下载安装包并在下载后立即用Get-FileHash -Algorithm SHA256与 toolset 中声明的sha256比对不一致即抛出checksum mismatch异常这正是sha256字段的消费点。symlinks为常用版本建立别名symlinks数组允许为某次安装额外建立指向它的符号链接。例如在 toolset-15.json 中26.1.1版本的条目声明了symlinks: [26.1]意味着还会生成/Applications/Xcode_26.1.app - /Applications/Xcode_26.1.1.app。其底层实现为 Build-XcodeSymlinks它用New-Item -ItemType SymbolicLink为每个别名创建链接。install_runtimes模拟器 Runtime 安装策略install_runtimes控制 Xcode 附带模拟器 RuntimeiOS、watchOS、tvOS 等的安装行为支持三种取值default—— 安装全部默认 Runtime。对应源码中xcodebuild -downloadAllPlatforms的调用。none—— 跳过 Runtime 安装镜像构建不执行任何下载。Hashtable对象数组—— 手动逐平台选择安装内容必填键iOS、watchOS、tvOSarm64 镜像额外要求visionOS源码 Install-XcodeAdditionalSimulatorRuntimes 中仅当$Arch -eq arm64时才把visionOS加入有效平台列表每个键的值为字符串数组元素可以是default安装该平台的默认 Runtime对应xcodebuild -downloadPlatform platformskip跳过该平台具体版本号semver例如18.2、2.2、18.3.1对应xcodebuild -downloadPlatform platform -buildVersion versionApple 构建号build number例如22E5216h、17A577。源码中的校验逻辑Xcode.Installer.psm1规定版本值要么匹配^\d{1,2}\.\d(\.\d)?$的 semver 模式要么匹配^[a-zA-Z0-9]{6,8}$的构建号模式否则直接抛错——这保证了错误配置在构建期即被拦截而不是生成一个残缺的镜像。两种书写格式字符串格式适用于简单的默认/跳过策略versions: [ { link: 16_beta_4, version: 16.0.0-Beta.416A5211f, symlinks: [16.0], install_runtimes: none, sha256: 4270cd8021b2f7f512ce91bfc4423b25bccab36cdab21834709d798c8daade72}, { link: 15.4, version: 15.4.015F31d, install_runtimes: default, sha256: 82d3d61804ff3f4c7c82085e91dc701037ddaa770e542848b2477e22f4e8aa7a} ]块格式适用于精细控制每个平台的 Runtimeversions: [ { link: 16.2, version: 16.216C5032a, sha256: 0e367d06eb7c334ea143bada5e4422f56688aabff571bedf0d2ad9434b7290de, install_runtimes: [ { iOS: [18.0, 18.1, 18.2] }, { watchOS: default }, { tvOS: default }, { visionOS: 2.2 } ] }, { link: 16.1, version: 16.116B40, sha256: 8ca961d55981f983d21b99a95a6b0ac04905b837f6e11346ee86d28f12afe720, install_runtimes: default } ]注意块格式中每个键的值可以是字符串如default也可以是数组如[18.0, 18.1, 18.2]源码中的ConvertTo-Json -Compress | ConvertFrom-Json -AsHashtable转换逻辑会兼容这两种写法。真实工具集 toolset-15.json 中的26.2条目即是块格式的完整范例同时覆盖 x64 与 arm64arm64 条目额外包含visionOS键。default默认 Xcode 版本xcode.default指定镜像默认激活的 Xcode取值必须与versions中某个条目的link匹配。例如default: 11.2configure-xcode.sh 会读取.xcode.default并在遍历完所有版本、擦除模拟器数据之后执行sudo xcode-select -s /Applications/Xcode_${DEFAULT_XCODE_VERSION}.app/Contents/Developer将其设为系统默认。若 default 与某个link不匹配工具集校验测试会直接失败见下文。Android 配置详解toolset 的android部分描述 Android SDK 组件的安装策略。原文档记载了四项基础属性属性含义示例platform-list要安装的 Android 平台API 级别数组[ android-29, android-28, android-27 ]build-tools要安装的构建工具版本数组[ 29.0.2, 29.0.1, 29.0.0, 28.0.3 ]extras要安装的 extra 组件数组[ google;google_play_services, intel;Hardware_Accelerated_Execution_Manager ]addons要安装的 add-on 组件数组[ addon-google_apis-google-24, addon-google_apis-google-23 ]需要说明的是以上属性描述的是 toolset 文档定义的最小接口而当前仓库实际工具集如 toolset-15.json中的android键在此基础上演进出更完整的结构android: { cmdline-tools: commandlinetools-mac-12266719_latest.zip, sdk-tools: sdk-tools-darwin-4333796.zip, platform_min_version: 34, build_tools_min_version: 35.0.0, extras: [ android;m2repository, google;m2repository, google;google_play_services ], addons: [], additional_tools: [ cmake;3.31.5, cmake;4.1.2 ], ndk: { default: 27, versions: [ 27, 28, 29 ] } }其中extras、addons沿用了文档语义platform_min_version与build_tools_min_version表示最低版本 该版本的全部已发布版本都会安装比文档中的显式数组更省维护成本。install-android-sdk.sh 是这些字段的消费方get_toolset_value .android.platform_min_version与.android.build_tools_min_version取得最低版本再由add_filtered_installation_components按版本号排序过滤出符合条件的组件列表.android.extras[]、.android.addons[]、.android.additional_tools[]分别展开为 SDK 组件参数.android.ndk.versions[]与.android.ndk.default控制 NDK 主版本清单及默认版本脚本通过sdkmanager --list | grep ndk;${majorVersion}...解析出该主版本对应的最新完整 NDK 版本号.android.cmdline-tools指定命令行工具压缩包名若取值为latest脚本会在线解析 Google 仓库 XML 自动获取最新版本install-android-sdk.sh。Toolset JSON 校验Pester 测试为保证 toolset 文件在构建期就合法、自洽仓库提供了专门的测试文件 images/macos/scripts/tests/Toolset.Tests.ps1基于 PowerShell 的 Pester 框架扫描当前目录下所有toolset-*.json文件逐个执行Test-Json断言其为合法 JSON对每个工具集断言xcode.default已定义Should -BeTrue检查存在性断言xcode.default的值出现在xcode.versions的link列表中即默认版本必须真实存在于待安装清单中。运行方式在测试文件所在目录执行 PowerShellInvoke-Pester该测试与 RunAll-Tests.ps1 中其他镜像测试一同构成镜像发布前的质量门禁确保任何对 toolset 的修改要么合法落地、要么在 CI 阶段被拒绝。从真实工具集看完整字段除 Xcode 与 Android 外当前仓库的 toolset 还包含其他软件栈的声明详见 toolset-15.json阅读时可一并了解java按x64/arm64声明default与versionstoolcache声明 Python、Node、Go、Ruby 的版本通配符如3.14.*、版本清单url与平台Configure-Toolset.ps1 会据此把GOROOT_{0}_{1}_X64等模板渲染为环境变量写入~/.bashrcInstall-Toolset.ps1 则按版本清单从 GitHub release 资产安装对应工具powershellModules、brewcommon_packages/cask_packages、gcc、dotnet、ruby、node、llvm、php、pwsh等分别被对应的install-*.sh脚本消费如 install-ruby.sh、install-gcc.sh。其中xcode、java、toolcache等多数顶层键都采用x64/arm64双分支结构与 Xcode.Installer.psm1 中按架构选择visionOS等平台的处理方式一致这也提醒读者修改 toolset 时务必同时维护两个架构分支避免构建出只有单架构可用的镜像。小结toolset JSON 是 macOS runner 镜像的声明式配置中心Xcode 部分的link、version、symlinks、sha256、install_runtimes与default共同决定了装哪些 Xcode、装哪些模拟器 Runtime、默认用哪个Android 部分的extras、addons及实际演化出的platform_min_version、build_tools_min_version、ndk等字段决定了 Android SDK 的安装面而 Pester 校验测试从语法合法性与语义一致性两个层面为配置质量兜底。掌握这套结构即可安全地定制属于自己的 macOS runner 镜像软件栈。【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 runner-images macOS 镜像 Toolset JSON 结构完全指南：Xcode 与 Android 配置详解
runner-images macOS 镜像 Toolset JSON 结构完全指南Xcode 与 Android 配置详解【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images本文基于 GitHub Actions runner-images 仓库中 images/macos/toolsets/Readme.md 展开深入讲解 macOS runner 镜像中 toolset JSON 的完整结构与配置语义并结合 Xcode.Installer.psm1、install-android-sdk.sh 等源码说明每个字段如何被真实消费。读完本文你将掌握如何编写、校验和扩展 toolset 文件从而控制镜像中安装的 Xcode 版本、模拟器 Runtime 以及 Android SDK 组件。Toolset 在 macOS 镜像中的角色toolset JSON 是 macOS runner 镜像生成流程的配置大脑。它被存放在 images/macos/toolsets/ 目录下以toolset-版本.json命名例如toolset-14.json、toolset-15.json、toolset-26.json。镜像构建脚本通过统一的入口读取它Common.Helpers.psm1 中的Get-ToolsetContent函数读取IMAGE_FOLDER环境变量指向的目录下的toolset.json并将其解析为 PowerShell 对象而 Bash 侧的脚本则通过get_toolset_value .xcode.versions...这类 jq 表达式按 JSON Path 取值。也就是说toolset 文件决定了镜像里装什么、装哪个版本、默认用哪个是镜像可复现性的核心保证。整个 macOS 镜像目录images/macos/按 OS 主版本划分 toolset 文件同一文件内部又按架构x64/arm64区分软件版本从而支持 Intel 与 Apple Silicon 两套并行配置。Xcode 配置详解Xcode 是 macOS 镜像中最重要的组件toolset 对它的描述也最细致。顶层结构如下xcode: { default: 16.4, x64: { versions: [ ... ] }, arm64: { versions: [ ... ] } }versions已安装 Xcode 版本清单versions是对象数组数组中每个对象描述一个将被安装的 Xcode 版本包含以下属性属性含义linkXcode 在镜像中的安装位置标识实际路径为/Applications/Xcode_link.appversion将被下载安装的 Xcode 版本号对应.xip安装包文件名symlinks需要为当前版本创建的别名符号链接列表sha256用于校验 Xcode 安装包完整性的 SHA-256 哈希install_runtimes控制模拟器 Runtime 的安装行为见下文filename下载文件名较新工具集中出现例如Xcode_26.3_Universal见 toolset-15.jsonlink与安装路径的对应关系在 Xcode.Helpers.psm1 中有直接实现Get-XcodeRootPath返回/Applications/Xcode_$Version.app。因此link: 15.4对应/Applications/Xcode_15.4.app。version 与 link 的命名规则version字段携带完整的版本与构建信息用或-分隔例如16.2.0-Beta.316C5023fBeta 版或16.2_Release_Candidate16C5031cRelease Candidate它会精确匹配.xip文件名。而link使用_代替空格例如16.2_Release_Candidate或16.1。原文档给出了 Apple 开发者站点下载 URL 的拼接模式DOWNLOAD_URLhttps://download.developer.apple.com/Developer_Tools/$SOURCE_FILE_LOCATION/$SOURCE_FILE_NAME.$FILE_EXTENSION SOURCE_FILE_NAMEXcode_$link SOURCE_FILE_LOCATIONXcode_$link FILE_EXTENSIONxip即link直接参与构建下载目录名与文件名。在实际镜像构建中Xcode.Installer.psm1 的Invoke-DownloadXcodeArchive通过${env:XCODE_INSTALL_STORAGE_URL}环境变量拼接Xcode-{Version}.xip下载安装包并在下载后立即用Get-FileHash -Algorithm SHA256与 toolset 中声明的sha256比对不一致即抛出checksum mismatch异常这正是sha256字段的消费点。symlinks为常用版本建立别名symlinks数组允许为某次安装额外建立指向它的符号链接。例如在 toolset-15.json 中26.1.1版本的条目声明了symlinks: [26.1]意味着还会生成/Applications/Xcode_26.1.app - /Applications/Xcode_26.1.1.app。其底层实现为 Build-XcodeSymlinks它用New-Item -ItemType SymbolicLink为每个别名创建链接。install_runtimes模拟器 Runtime 安装策略install_runtimes控制 Xcode 附带模拟器 RuntimeiOS、watchOS、tvOS 等的安装行为支持三种取值default—— 安装全部默认 Runtime。对应源码中xcodebuild -downloadAllPlatforms的调用。none—— 跳过 Runtime 安装镜像构建不执行任何下载。Hashtable对象数组—— 手动逐平台选择安装内容必填键iOS、watchOS、tvOSarm64 镜像额外要求visionOS源码 Install-XcodeAdditionalSimulatorRuntimes 中仅当$Arch -eq arm64时才把visionOS加入有效平台列表每个键的值为字符串数组元素可以是default安装该平台的默认 Runtime对应xcodebuild -downloadPlatform platformskip跳过该平台具体版本号semver例如18.2、2.2、18.3.1对应xcodebuild -downloadPlatform platform -buildVersion versionApple 构建号build number例如22E5216h、17A577。源码中的校验逻辑Xcode.Installer.psm1规定版本值要么匹配^\d{1,2}\.\d(\.\d)?$的 semver 模式要么匹配^[a-zA-Z0-9]{6,8}$的构建号模式否则直接抛错——这保证了错误配置在构建期即被拦截而不是生成一个残缺的镜像。两种书写格式字符串格式适用于简单的默认/跳过策略versions: [ { link: 16_beta_4, version: 16.0.0-Beta.416A5211f, symlinks: [16.0], install_runtimes: none, sha256: 4270cd8021b2f7f512ce91bfc4423b25bccab36cdab21834709d798c8daade72}, { link: 15.4, version: 15.4.015F31d, install_runtimes: default, sha256: 82d3d61804ff3f4c7c82085e91dc701037ddaa770e542848b2477e22f4e8aa7a} ]块格式适用于精细控制每个平台的 Runtimeversions: [ { link: 16.2, version: 16.216C5032a, sha256: 0e367d06eb7c334ea143bada5e4422f56688aabff571bedf0d2ad9434b7290de, install_runtimes: [ { iOS: [18.0, 18.1, 18.2] }, { watchOS: default }, { tvOS: default }, { visionOS: 2.2 } ] }, { link: 16.1, version: 16.116B40, sha256: 8ca961d55981f983d21b99a95a6b0ac04905b837f6e11346ee86d28f12afe720, install_runtimes: default } ]注意块格式中每个键的值可以是字符串如default也可以是数组如[18.0, 18.1, 18.2]源码中的ConvertTo-Json -Compress | ConvertFrom-Json -AsHashtable转换逻辑会兼容这两种写法。真实工具集 toolset-15.json 中的26.2条目即是块格式的完整范例同时覆盖 x64 与 arm64arm64 条目额外包含visionOS键。default默认 Xcode 版本xcode.default指定镜像默认激活的 Xcode取值必须与versions中某个条目的link匹配。例如default: 11.2configure-xcode.sh 会读取.xcode.default并在遍历完所有版本、擦除模拟器数据之后执行sudo xcode-select -s /Applications/Xcode_${DEFAULT_XCODE_VERSION}.app/Contents/Developer将其设为系统默认。若 default 与某个link不匹配工具集校验测试会直接失败见下文。Android 配置详解toolset 的android部分描述 Android SDK 组件的安装策略。原文档记载了四项基础属性属性含义示例platform-list要安装的 Android 平台API 级别数组[ android-29, android-28, android-27 ]build-tools要安装的构建工具版本数组[ 29.0.2, 29.0.1, 29.0.0, 28.0.3 ]extras要安装的 extra 组件数组[ google;google_play_services, intel;Hardware_Accelerated_Execution_Manager ]addons要安装的 add-on 组件数组[ addon-google_apis-google-24, addon-google_apis-google-23 ]需要说明的是以上属性描述的是 toolset 文档定义的最小接口而当前仓库实际工具集如 toolset-15.json中的android键在此基础上演进出更完整的结构android: { cmdline-tools: commandlinetools-mac-12266719_latest.zip, sdk-tools: sdk-tools-darwin-4333796.zip, platform_min_version: 34, build_tools_min_version: 35.0.0, extras: [ android;m2repository, google;m2repository, google;google_play_services ], addons: [], additional_tools: [ cmake;3.31.5, cmake;4.1.2 ], ndk: { default: 27, versions: [ 27, 28, 29 ] } }其中extras、addons沿用了文档语义platform_min_version与build_tools_min_version表示最低版本 该版本的全部已发布版本都会安装比文档中的显式数组更省维护成本。install-android-sdk.sh 是这些字段的消费方get_toolset_value .android.platform_min_version与.android.build_tools_min_version取得最低版本再由add_filtered_installation_components按版本号排序过滤出符合条件的组件列表.android.extras[]、.android.addons[]、.android.additional_tools[]分别展开为 SDK 组件参数.android.ndk.versions[]与.android.ndk.default控制 NDK 主版本清单及默认版本脚本通过sdkmanager --list | grep ndk;${majorVersion}...解析出该主版本对应的最新完整 NDK 版本号.android.cmdline-tools指定命令行工具压缩包名若取值为latest脚本会在线解析 Google 仓库 XML 自动获取最新版本install-android-sdk.sh。Toolset JSON 校验Pester 测试为保证 toolset 文件在构建期就合法、自洽仓库提供了专门的测试文件 images/macos/scripts/tests/Toolset.Tests.ps1基于 PowerShell 的 Pester 框架扫描当前目录下所有toolset-*.json文件逐个执行Test-Json断言其为合法 JSON对每个工具集断言xcode.default已定义Should -BeTrue检查存在性断言xcode.default的值出现在xcode.versions的link列表中即默认版本必须真实存在于待安装清单中。运行方式在测试文件所在目录执行 PowerShellInvoke-Pester该测试与 RunAll-Tests.ps1 中其他镜像测试一同构成镜像发布前的质量门禁确保任何对 toolset 的修改要么合法落地、要么在 CI 阶段被拒绝。从真实工具集看完整字段除 Xcode 与 Android 外当前仓库的 toolset 还包含其他软件栈的声明详见 toolset-15.json阅读时可一并了解java按x64/arm64声明default与versionstoolcache声明 Python、Node、Go、Ruby 的版本通配符如3.14.*、版本清单url与平台Configure-Toolset.ps1 会据此把GOROOT_{0}_{1}_X64等模板渲染为环境变量写入~/.bashrcInstall-Toolset.ps1 则按版本清单从 GitHub release 资产安装对应工具powershellModules、brewcommon_packages/cask_packages、gcc、dotnet、ruby、node、llvm、php、pwsh等分别被对应的install-*.sh脚本消费如 install-ruby.sh、install-gcc.sh。其中xcode、java、toolcache等多数顶层键都采用x64/arm64双分支结构与 Xcode.Installer.psm1 中按架构选择visionOS等平台的处理方式一致这也提醒读者修改 toolset 时务必同时维护两个架构分支避免构建出只有单架构可用的镜像。小结toolset JSON 是 macOS runner 镜像的声明式配置中心Xcode 部分的link、version、symlinks、sha256、install_runtimes与default共同决定了装哪些 Xcode、装哪些模拟器 Runtime、默认用哪个Android 部分的extras、addons及实际演化出的platform_min_version、build_tools_min_version、ndk等字段决定了 Android SDK 的安装面而 Pester 校验测试从语法合法性与语义一致性两个层面为配置质量兜底。掌握这套结构即可安全地定制属于自己的 macOS runner 镜像软件栈。【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考