向 runner-images 仓库贡献代码从提交 Pull Request 到为 GitHub Actions Runner 镜像新增工具【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images本文以 runner-imagesGitHub Actions runner images仓库的 CONTRIBUTING.md 为核心指南系统讲解开发者如何向该仓库提交高质量的 Pull Request、如何按平台规范为 Windows / Ubuntu / macOS 镜像新增工具包含安装脚本、Pester 验证测试与软件报告更新的完整链路以及仓库统一的 Bash / PowerShell 代码风格规范。读完本文你将掌握在该仓库中安全地添加一个可被镜像构建、验证并收录进官方文档的新工具的全部实操步骤。从贡献者的视角认识 runner-imagesrunner-images 仓库为 GitHub Actions 托管运行器提供预装大量开发工具的虚拟机镜像覆盖 Windows、Ubuntu、macOS 三大平台。镜像本身由 Packer 模板驱动在 Azure 上完成「创建临时 VM → 执行安装步骤 → 生成托管镜像」的流程详见 docs/create-image-and-azure-resources.md。因此任何一次工具新增本质上都是在为这套庞大的镜像生成流水线增加一个新的安装步骤其质量直接影响全球用户在 CI 中的构建体验。在提交任何代码之前请留意以下几点基础事实贡献以 MIT 许可 发布到公共领域参与即表示同意该许可条款项目附带 贡献者行为准则参与即表示遵守仓库中的安装脚本分为build安装工具与tests验证安装两套目录加上docs-gen生成软件报告三者共同构成一次工具贡献的完整闭环。提交 Pull Request 的标准流程官方推荐的 PR 提交流程如下每一步都对应仓库中真实存在的文件与脚本Fork 并克隆仓库git clone后即可在本地构建镜像进行验证。创建新分支git checkout -b my-branch-name。做出修改且修改必须同时包含三部分安装步骤、安装后的验证post-install validation、软件报告更新——三者缺一不可。通过「创建镜像并部署 VM」的方式测试修改具体操作见 docs/create-image-and-azure-resources.md该文档描述了使用 Packer 生成镜像、在 Azure 中创建资源组与 VM 的完整过程构建代理机上需要安装 Packer 1.8.2、Git、PowerShell 5.0 与 Azure CLI。推送分支并提交 Pull Request。提高 PR 被接受率的实践建议Windows 脚本遵循 PoshCode 社区维护的 PowerShell 风格指南Shell 脚本Linux 安装脚本目前暂无官方强制风格但应尽量保持与仓库现有脚本一致。在 PR 描述中完整说明为什么需要这个改动。让改动尽量聚焦多个相互独立的改动请拆分为多个 PR 分别提交。撰写良好的提交信息。针对新增工具的特殊要求确认该工具满足 README.md 中「预安装策略」Preinstallation Policy一节列出的软件准则先创建 Issue 并取得维护者批准再动手创建 PR——这是新增工具类贡献的硬性前置条件。新增工具到镜像全平台通用规则无论目标平台是哪个以下通用规则都适用每个新工具都必须配套验证脚本并更新软件报告脚本确保该工具被收录进官方生成的文档各镜像的 Readme。如果工具在多个平台macOS / Windows / Linux上可用尽量在尽可能多的平台上同时加入避免平台间工具集不一致。如果要安装多个版本优先把版本列表放入对应的toolset.json——这样用户可以灵活配置自己的构建也便于维护。参考示例images/windows/toolsets/toolset-2022.json其中toolcache、java、android、visualStudio等小节都采用「版本列表 default 默认版本」的结构。所有文件命名保持一致安装脚本、测试脚本、报告条目使用同一工具名。验证脚本应当保持简单且不改变镜像内容——它只负责「确认安装成功」不能顺手修改系统状态。toolset.json多版本工具的统一配置中心以 images/windows/toolsets/toolset-2022.json 为例工具版本可以这样声明java: { default: 8, versions: [ 8, 11, 17, 21, 25] }, node: { default: 22.* }, llvm: { version: 20 }toolcache小节则支持按架构arch与平台platform声明多个版本甚至可用通配符{ name: Python, url: https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json, arch: x64, platform: win32, versions: [ 3.10.*, 3.11.*, 3.12.*, 3.13.*, 3.14.* ], default: 3.12.* }Ubuntu 侧的 images/ubuntu/toolsets/toolset-2204.json 还包含apt.vital_packages/apt.common_packages/apt.cmd_packages等按 apt 包分类的列表以及dotnet、docker.components、pipx等小节。安装脚本侧通过 images/ubuntu/scripts/helpers/install.sh 中的get_toolset_value函数内部用jq按查询路径读取toolset.json读取这些配置$INSTALLER_SCRIPT_FOLDER/toolset.json即运行时工具集文件路径——这解释了为什么工具版本集中在 JSON 中声明即可被安装脚本消费。按平台新增工具WindowsPowerShell 安装脚本 Pester 验证 报告更新Windows 侧的一次完整工具贡献包含三个动作第一步编写安装脚本放入images/windows/scripts/build/目录。仓库中已有大量可参考的示例例如Install-Git.ps1、Install-NodeJS.ps1、Install-Rust.ps1、Install-PHP.ps1、Install-Toolset.ps1等完整列表见 images/windows/scripts/build 目录。images/windows/scripts/helpers/ImageHelpers.psm1 提供了大量可直接复用的辅助函数文档明确列出的包括Install-ChocoPackage—— 通过 Chocolatey 安装包来自ChocoHelpers.ps1Install-Binary—— 下载并解压二进制Install-VSIXFromFile/Install-VSIXFromUrl—— 安装 Visual Studio 扩展Invoke-DownloadWithRetry—— 带重试的下载Test-IsWin22/Test-IsWin25/Test-IsWin11/Test-IsArm64/Test-IsX64—— 平台与架构判断。其余导出函数还包括Get-GithubReleasesByVersion、Resolve-GithubReleaseAssetUrl、Get-ChecksumFromGithubRelease、Get-ChecksumFromUrl、Test-FileChecksum、Test-FileSignature供应链安全校验、Update-Environment以及来自PathHelpers.ps1的Add-MachinePathItem等。第二步编写验证脚本放入images/windows/scripts/tests/目录验证脚本基于Pester v5测试足够复杂时创建独立的*.Tests.ps1如Git.Tests.ps1、Node.Tests.ps1、Docker.Tests.ps1、VisualStudio.Tests.ps1见 images/windows/scripts/tests 目录简单测试则并入 images/windows/scripts/tests/Tools.Tests.ps1必须在安装脚本末尾加上Invoke-PesterTests -TestFile testFileName [-TestName describeName]确保构建镜像时测试会被执行。以 Ubuntu 侧的 images/ubuntu/scripts/tests/Helpers.psm1 中Invoke-PesterTests的实现为参照可以理解其内部机制它根据TestFile在镜像内的/imagegeneration/tests/TestFile.Tests.ps1路径定位测试文件自动导入 Pester 模块通过[PesterConfiguration]设置Run.Path、Output.Verbosity Detailed并临时将$ErrorActionPreference切换为Stop以保证静默错误也会导致测试失败最终校验「失败数为 0 且通过数 跳过数 0」否则抛出异常终止构建。第三步更新软件报告生成器images/windows/scripts/docs-gen/Generate-SoftwareReport.ps1。该脚本负责生成镜像的 README例如 images/windows/Windows2022-Readme.md底层使用 MarkdownPS 模块该模块本身也出现在 images/windows/toolsets/toolset-2022.json 的powershellModules列表中。不更新它新工具就不会出现在官方文档中。UbuntuBash 安装脚本安装 验证一体 报告更新Ubuntu 侧的结构略有不同——安装与验证在同一脚本中完成把安装脚本放入images/ubuntu/scripts/build/目录。文档明确推荐以 images/ubuntu/scripts/build/install-github-cli.sh 为起点——该脚本是很好的模板展示了完整的「下载 → 校验和验证 → 安装 → 运行测试」流程通过is_x64/is_arm64判断架构并设置gh_cli_arch用resolve_github_release_asset_url解析 GitHub Release 资产 URL用download_with_retry下载.deb包供应链安全下载checksums.txt后用get_checksum_from_url取 SHA256 哈希再经use_checksum_comparison比对本地文件哈希全部通过后才继续apt-get install安装最后调用invoke_tests CLI.Tools GitHub CLI触发对应的 Pester 测试。使用 images/ubuntu/scripts/helpers/install.sh 中的辅助函数简化安装流程。该文件提供的函数包括download_with_retry带 20 次重试、间隔 30 秒的下载、get_toolset_value、get_github_releases_by_version、resolve_github_release_asset_url、get_checksum_from_github_release、get_checksum_from_url、use_checksum_comparison校验和比对等。另可参考os.sh架构/系统判断与etc-environment.sh环境变量持久化。验证部分在任何安装问题时必须以exit 1退出使构建立即失败。更新 images/ubuntu/scripts/docs-gen/Generate-SoftwareReport.ps1该脚本生成如 images/ubuntu/Ubuntu2204-Readme.md 的 README同样使用 MarkdownPS。Ubuntu 的 Pester 测试文件位于 images/ubuntu/scripts/tests 目录例如CLI.Tools.Tests.ps1、Node.Tests.ps1、Java.Tests.ps1等。以 images/ubuntu/scripts/tests/CLI.Tools.Tests.ps1 为例每个Describe块针对一个 CLI 工具用Should -ReturnZeroExitCode断言命令成功退出某些测试还通过-Skip:((-not (Test-IsUbuntu22-X64)))按平台/架构条件跳过这与 Windows 侧的Test-IsWin22等辅助函数思路一致。macOS当前暂不接受外部 PRmacOS 的源码虽然就存放在本仓库images/macos/包含templates、scripts、toolsets与各版本 Readme但镜像生成 CI 目前不支持外部贡献因此现阶段无法接受 macOS 相关的 Pull Request。维护团队正在筹备接受贡献的 macOS CI在此之前请通过提交 Issue 的方式来提出工具请求。代码风格指南「简洁代码」的原则适用于所有语言变量、函数、文件名要有意义函数保持短小简单用注释说明代码做什么保持一致的代码风格、命名约定与文件结构。文件结构通用要求每个文件头部应包含标题与简短描述每个文件末尾以换行符结尾用空行分隔逻辑代码块但不要滥用不在块/函数的开头和结尾加空行不在逻辑相关的语句之间加空行避免行尾空白trailing whitespace。Bash 脚本规范命名约定变量用小写字母常量用大写字母单词间用下划线分隔。脚本结构每个脚本必须以如下 shebang 开头使脚本在任一条命令失败时立即退出-e即 errexit#!/bin/bash -eshebang 之后添加如下格式的文件头################################################################################ ## File: filename ## Desc: short description of what the script does ################################################################################然后导入脚本用到的辅助脚本只导入实际用到的不要全量导入Linuxsource $HELPER_SCRIPTS/os.sh source $HELPER_SCRIPTS/install.sh source $HELPER_SCRIPTS/etc-environment.shmacOSsource ~/utils/utils.sh缩进与换行使用 4 空格缩进if/for/while与[[之间、[[与条件之间留 1 个空格then/do放在新行短小的if/for/while可用单行格式长管道用\折行。其他建议命令替换使用$()而非反引号条件表达式使用[[而非[优先使用长选项而非短键但有少量公认例外如tar -xzf、apt-get -yqq、curl -sSLf、wget -qO-这些在仓库现有安装脚本中随处可见。PowerShell 脚本规范命名约定变量用 camelCase常量用大写字母函数名使用Verb-Noun形式且采用 PascalCase。脚本结构每个脚本以如下文件头开始################################################################################ ## File: filename ## Desc: short description of what the script does ################################################################################然后声明脚本使用的函数。Linux 与 macOS 下可导入辅助模块按需导入LinuxImport-Module $env:HELPER_SCRIPTS/Tests.Helpers.psm1 -DisableNameCheckingmacOSImport-Module $env:HOME/image-generation/helpers/Common.Helpers.psm1 Import-Module $env:HOME/image-generation/helpers/Xcode.Helpers.psm1 -DisableNameChecking缩进与换行使用 4 空格缩进if/elseif/foreach与(之间留 1 个空格但(与条件之间不留管道|与重定向操作符前后加空格哈希表中的属性对齐花括号采用 1TBS 风格——语句块较长时换行缩进并以独立行收尾短语句块可与语句同行。参考仓库示例function Show-Example1 { $exampleVariable Get-ChildItem $env:TEMP $exampleVariable | ForEach-Object { $itemName $_.Name $itemPath $_.FullName } } $Example2 | Some-Function -Arguments {Parameter1 Disabled}其他建议避免使用别名长管道用反引号折行注意反引号后的行尾空白会导致错误或改用 splatting 传参例如# Instead of this Copy-Item -Path test.txt -Destination test2.txt -WhatIf # you can use this $HashArguments { Path test.txt Destination test2.txt WhatIf $true } Copy-Item HashArguments此外验证命令的退出码编写函数时提供描述其功能的 docstring。对照源码自查一次贡献的完整闭环综合以上内容一次符合仓库预期的工具贡献应能回答以下问题均可对照源码验证安装脚本是否放在images/platform/scripts/build/下并复用了 images/ubuntu/scripts/helpers/install.sh 或 images/windows/scripts/helpers/ImageHelpers.psm1 中的辅助函数验证是否到位Ubuntu 脚本是否在失败时exit 1Windows 脚本末尾是否调用了Invoke-PesterTests测试文件是否存在于images/platform/scripts/tests/下且基于 Pester v5参考 images/ubuntu/scripts/tests/CLI.Tools.Tests.ps1 的Describe/It/Should -ReturnZeroExitCode写法版本配置是否写入了对应镜像的toolset.json如 images/windows/toolsets/toolset-2022.json、images/ubuntu/toolsets/toolset-2204.json供get_toolset_value等函数消费软件报告是否更新了 images/windows/scripts/docs-gen/Generate-SoftwareReport.ps1 或 images/ubuntu/scripts/docs-gen/Generate-SoftwareReport.ps1使新工具出现在对应镜像的 Readme 中代码风格是否符合本文「代码风格指南」一节shebang、文件头、命名、缩进、辅助函数导入只有安装、验证、报告三部分全部就绪改动才能通过镜像构建的完整流水线最终被维护者合入。【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 向 runner-images 仓库贡献代码：从提交 Pull Request 到为 GitHub Actions Runner 镜像新增工具
向 runner-images 仓库贡献代码从提交 Pull Request 到为 GitHub Actions Runner 镜像新增工具【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images本文以 runner-imagesGitHub Actions runner images仓库的 CONTRIBUTING.md 为核心指南系统讲解开发者如何向该仓库提交高质量的 Pull Request、如何按平台规范为 Windows / Ubuntu / macOS 镜像新增工具包含安装脚本、Pester 验证测试与软件报告更新的完整链路以及仓库统一的 Bash / PowerShell 代码风格规范。读完本文你将掌握在该仓库中安全地添加一个可被镜像构建、验证并收录进官方文档的新工具的全部实操步骤。从贡献者的视角认识 runner-imagesrunner-images 仓库为 GitHub Actions 托管运行器提供预装大量开发工具的虚拟机镜像覆盖 Windows、Ubuntu、macOS 三大平台。镜像本身由 Packer 模板驱动在 Azure 上完成「创建临时 VM → 执行安装步骤 → 生成托管镜像」的流程详见 docs/create-image-and-azure-resources.md。因此任何一次工具新增本质上都是在为这套庞大的镜像生成流水线增加一个新的安装步骤其质量直接影响全球用户在 CI 中的构建体验。在提交任何代码之前请留意以下几点基础事实贡献以 MIT 许可 发布到公共领域参与即表示同意该许可条款项目附带 贡献者行为准则参与即表示遵守仓库中的安装脚本分为build安装工具与tests验证安装两套目录加上docs-gen生成软件报告三者共同构成一次工具贡献的完整闭环。提交 Pull Request 的标准流程官方推荐的 PR 提交流程如下每一步都对应仓库中真实存在的文件与脚本Fork 并克隆仓库git clone后即可在本地构建镜像进行验证。创建新分支git checkout -b my-branch-name。做出修改且修改必须同时包含三部分安装步骤、安装后的验证post-install validation、软件报告更新——三者缺一不可。通过「创建镜像并部署 VM」的方式测试修改具体操作见 docs/create-image-and-azure-resources.md该文档描述了使用 Packer 生成镜像、在 Azure 中创建资源组与 VM 的完整过程构建代理机上需要安装 Packer 1.8.2、Git、PowerShell 5.0 与 Azure CLI。推送分支并提交 Pull Request。提高 PR 被接受率的实践建议Windows 脚本遵循 PoshCode 社区维护的 PowerShell 风格指南Shell 脚本Linux 安装脚本目前暂无官方强制风格但应尽量保持与仓库现有脚本一致。在 PR 描述中完整说明为什么需要这个改动。让改动尽量聚焦多个相互独立的改动请拆分为多个 PR 分别提交。撰写良好的提交信息。针对新增工具的特殊要求确认该工具满足 README.md 中「预安装策略」Preinstallation Policy一节列出的软件准则先创建 Issue 并取得维护者批准再动手创建 PR——这是新增工具类贡献的硬性前置条件。新增工具到镜像全平台通用规则无论目标平台是哪个以下通用规则都适用每个新工具都必须配套验证脚本并更新软件报告脚本确保该工具被收录进官方生成的文档各镜像的 Readme。如果工具在多个平台macOS / Windows / Linux上可用尽量在尽可能多的平台上同时加入避免平台间工具集不一致。如果要安装多个版本优先把版本列表放入对应的toolset.json——这样用户可以灵活配置自己的构建也便于维护。参考示例images/windows/toolsets/toolset-2022.json其中toolcache、java、android、visualStudio等小节都采用「版本列表 default 默认版本」的结构。所有文件命名保持一致安装脚本、测试脚本、报告条目使用同一工具名。验证脚本应当保持简单且不改变镜像内容——它只负责「确认安装成功」不能顺手修改系统状态。toolset.json多版本工具的统一配置中心以 images/windows/toolsets/toolset-2022.json 为例工具版本可以这样声明java: { default: 8, versions: [ 8, 11, 17, 21, 25] }, node: { default: 22.* }, llvm: { version: 20 }toolcache小节则支持按架构arch与平台platform声明多个版本甚至可用通配符{ name: Python, url: https://raw.githubusercontent.com/actions/python-versions/main/versions-manifest.json, arch: x64, platform: win32, versions: [ 3.10.*, 3.11.*, 3.12.*, 3.13.*, 3.14.* ], default: 3.12.* }Ubuntu 侧的 images/ubuntu/toolsets/toolset-2204.json 还包含apt.vital_packages/apt.common_packages/apt.cmd_packages等按 apt 包分类的列表以及dotnet、docker.components、pipx等小节。安装脚本侧通过 images/ubuntu/scripts/helpers/install.sh 中的get_toolset_value函数内部用jq按查询路径读取toolset.json读取这些配置$INSTALLER_SCRIPT_FOLDER/toolset.json即运行时工具集文件路径——这解释了为什么工具版本集中在 JSON 中声明即可被安装脚本消费。按平台新增工具WindowsPowerShell 安装脚本 Pester 验证 报告更新Windows 侧的一次完整工具贡献包含三个动作第一步编写安装脚本放入images/windows/scripts/build/目录。仓库中已有大量可参考的示例例如Install-Git.ps1、Install-NodeJS.ps1、Install-Rust.ps1、Install-PHP.ps1、Install-Toolset.ps1等完整列表见 images/windows/scripts/build 目录。images/windows/scripts/helpers/ImageHelpers.psm1 提供了大量可直接复用的辅助函数文档明确列出的包括Install-ChocoPackage—— 通过 Chocolatey 安装包来自ChocoHelpers.ps1Install-Binary—— 下载并解压二进制Install-VSIXFromFile/Install-VSIXFromUrl—— 安装 Visual Studio 扩展Invoke-DownloadWithRetry—— 带重试的下载Test-IsWin22/Test-IsWin25/Test-IsWin11/Test-IsArm64/Test-IsX64—— 平台与架构判断。其余导出函数还包括Get-GithubReleasesByVersion、Resolve-GithubReleaseAssetUrl、Get-ChecksumFromGithubRelease、Get-ChecksumFromUrl、Test-FileChecksum、Test-FileSignature供应链安全校验、Update-Environment以及来自PathHelpers.ps1的Add-MachinePathItem等。第二步编写验证脚本放入images/windows/scripts/tests/目录验证脚本基于Pester v5测试足够复杂时创建独立的*.Tests.ps1如Git.Tests.ps1、Node.Tests.ps1、Docker.Tests.ps1、VisualStudio.Tests.ps1见 images/windows/scripts/tests 目录简单测试则并入 images/windows/scripts/tests/Tools.Tests.ps1必须在安装脚本末尾加上Invoke-PesterTests -TestFile testFileName [-TestName describeName]确保构建镜像时测试会被执行。以 Ubuntu 侧的 images/ubuntu/scripts/tests/Helpers.psm1 中Invoke-PesterTests的实现为参照可以理解其内部机制它根据TestFile在镜像内的/imagegeneration/tests/TestFile.Tests.ps1路径定位测试文件自动导入 Pester 模块通过[PesterConfiguration]设置Run.Path、Output.Verbosity Detailed并临时将$ErrorActionPreference切换为Stop以保证静默错误也会导致测试失败最终校验「失败数为 0 且通过数 跳过数 0」否则抛出异常终止构建。第三步更新软件报告生成器images/windows/scripts/docs-gen/Generate-SoftwareReport.ps1。该脚本负责生成镜像的 README例如 images/windows/Windows2022-Readme.md底层使用 MarkdownPS 模块该模块本身也出现在 images/windows/toolsets/toolset-2022.json 的powershellModules列表中。不更新它新工具就不会出现在官方文档中。UbuntuBash 安装脚本安装 验证一体 报告更新Ubuntu 侧的结构略有不同——安装与验证在同一脚本中完成把安装脚本放入images/ubuntu/scripts/build/目录。文档明确推荐以 images/ubuntu/scripts/build/install-github-cli.sh 为起点——该脚本是很好的模板展示了完整的「下载 → 校验和验证 → 安装 → 运行测试」流程通过is_x64/is_arm64判断架构并设置gh_cli_arch用resolve_github_release_asset_url解析 GitHub Release 资产 URL用download_with_retry下载.deb包供应链安全下载checksums.txt后用get_checksum_from_url取 SHA256 哈希再经use_checksum_comparison比对本地文件哈希全部通过后才继续apt-get install安装最后调用invoke_tests CLI.Tools GitHub CLI触发对应的 Pester 测试。使用 images/ubuntu/scripts/helpers/install.sh 中的辅助函数简化安装流程。该文件提供的函数包括download_with_retry带 20 次重试、间隔 30 秒的下载、get_toolset_value、get_github_releases_by_version、resolve_github_release_asset_url、get_checksum_from_github_release、get_checksum_from_url、use_checksum_comparison校验和比对等。另可参考os.sh架构/系统判断与etc-environment.sh环境变量持久化。验证部分在任何安装问题时必须以exit 1退出使构建立即失败。更新 images/ubuntu/scripts/docs-gen/Generate-SoftwareReport.ps1该脚本生成如 images/ubuntu/Ubuntu2204-Readme.md 的 README同样使用 MarkdownPS。Ubuntu 的 Pester 测试文件位于 images/ubuntu/scripts/tests 目录例如CLI.Tools.Tests.ps1、Node.Tests.ps1、Java.Tests.ps1等。以 images/ubuntu/scripts/tests/CLI.Tools.Tests.ps1 为例每个Describe块针对一个 CLI 工具用Should -ReturnZeroExitCode断言命令成功退出某些测试还通过-Skip:((-not (Test-IsUbuntu22-X64)))按平台/架构条件跳过这与 Windows 侧的Test-IsWin22等辅助函数思路一致。macOS当前暂不接受外部 PRmacOS 的源码虽然就存放在本仓库images/macos/包含templates、scripts、toolsets与各版本 Readme但镜像生成 CI 目前不支持外部贡献因此现阶段无法接受 macOS 相关的 Pull Request。维护团队正在筹备接受贡献的 macOS CI在此之前请通过提交 Issue 的方式来提出工具请求。代码风格指南「简洁代码」的原则适用于所有语言变量、函数、文件名要有意义函数保持短小简单用注释说明代码做什么保持一致的代码风格、命名约定与文件结构。文件结构通用要求每个文件头部应包含标题与简短描述每个文件末尾以换行符结尾用空行分隔逻辑代码块但不要滥用不在块/函数的开头和结尾加空行不在逻辑相关的语句之间加空行避免行尾空白trailing whitespace。Bash 脚本规范命名约定变量用小写字母常量用大写字母单词间用下划线分隔。脚本结构每个脚本必须以如下 shebang 开头使脚本在任一条命令失败时立即退出-e即 errexit#!/bin/bash -eshebang 之后添加如下格式的文件头################################################################################ ## File: filename ## Desc: short description of what the script does ################################################################################然后导入脚本用到的辅助脚本只导入实际用到的不要全量导入Linuxsource $HELPER_SCRIPTS/os.sh source $HELPER_SCRIPTS/install.sh source $HELPER_SCRIPTS/etc-environment.shmacOSsource ~/utils/utils.sh缩进与换行使用 4 空格缩进if/for/while与[[之间、[[与条件之间留 1 个空格then/do放在新行短小的if/for/while可用单行格式长管道用\折行。其他建议命令替换使用$()而非反引号条件表达式使用[[而非[优先使用长选项而非短键但有少量公认例外如tar -xzf、apt-get -yqq、curl -sSLf、wget -qO-这些在仓库现有安装脚本中随处可见。PowerShell 脚本规范命名约定变量用 camelCase常量用大写字母函数名使用Verb-Noun形式且采用 PascalCase。脚本结构每个脚本以如下文件头开始################################################################################ ## File: filename ## Desc: short description of what the script does ################################################################################然后声明脚本使用的函数。Linux 与 macOS 下可导入辅助模块按需导入LinuxImport-Module $env:HELPER_SCRIPTS/Tests.Helpers.psm1 -DisableNameCheckingmacOSImport-Module $env:HOME/image-generation/helpers/Common.Helpers.psm1 Import-Module $env:HOME/image-generation/helpers/Xcode.Helpers.psm1 -DisableNameChecking缩进与换行使用 4 空格缩进if/elseif/foreach与(之间留 1 个空格但(与条件之间不留管道|与重定向操作符前后加空格哈希表中的属性对齐花括号采用 1TBS 风格——语句块较长时换行缩进并以独立行收尾短语句块可与语句同行。参考仓库示例function Show-Example1 { $exampleVariable Get-ChildItem $env:TEMP $exampleVariable | ForEach-Object { $itemName $_.Name $itemPath $_.FullName } } $Example2 | Some-Function -Arguments {Parameter1 Disabled}其他建议避免使用别名长管道用反引号折行注意反引号后的行尾空白会导致错误或改用 splatting 传参例如# Instead of this Copy-Item -Path test.txt -Destination test2.txt -WhatIf # you can use this $HashArguments { Path test.txt Destination test2.txt WhatIf $true } Copy-Item HashArguments此外验证命令的退出码编写函数时提供描述其功能的 docstring。对照源码自查一次贡献的完整闭环综合以上内容一次符合仓库预期的工具贡献应能回答以下问题均可对照源码验证安装脚本是否放在images/platform/scripts/build/下并复用了 images/ubuntu/scripts/helpers/install.sh 或 images/windows/scripts/helpers/ImageHelpers.psm1 中的辅助函数验证是否到位Ubuntu 脚本是否在失败时exit 1Windows 脚本末尾是否调用了Invoke-PesterTests测试文件是否存在于images/platform/scripts/tests/下且基于 Pester v5参考 images/ubuntu/scripts/tests/CLI.Tools.Tests.ps1 的Describe/It/Should -ReturnZeroExitCode写法版本配置是否写入了对应镜像的toolset.json如 images/windows/toolsets/toolset-2022.json、images/ubuntu/toolsets/toolset-2204.json供get_toolset_value等函数消费软件报告是否更新了 images/windows/scripts/docs-gen/Generate-SoftwareReport.ps1 或 images/ubuntu/scripts/docs-gen/Generate-SoftwareReport.ps1使新工具出现在对应镜像的 Readme 中代码风格是否符合本文「代码风格指南」一节shebang、文件头、命名、缩进、辅助函数导入只有安装、验证、报告三部分全部就绪改动才能通过镜像构建的完整流水线最终被维护者合入。【免费下载链接】runner-imagesGitHub Actions runner images项目地址: https://gitcode.com/GitHub_Trending/ru/runner-images创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考