本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # CodeBuild 的建置規格參考 本主題提供關於建置規格 (Buildspec) 檔案的重要參考資訊。*buildspec* 是組建命令和相關設定的集合，採用 YAML 格式，可供 CodeBuild 用來執行組建。您可以在原始程式碼中包含 buildspec，也可以在建立建置專案時定義 buildspec。如需組建規格運作方式的詳細資訊，請參閱[CodeBuild 的運作方式](concepts.md#concepts-how-it-works)。 **Topics** + [Buildspec 檔案名稱和儲存位置](#build-spec-ref-name-storage) + [Buildspec 語法](#build-spec-ref-syntax) + [Buildspec 範例](#build-spec-ref-example) + [Buildspec 版本](#build-spec-ref-versions) + [批次建置 buildspec 參考](batch-build-buildspec.md) ## Buildspec 檔案名稱和儲存位置 若您隨著來源碼併入組建規格，依預設，組建規格檔案的名稱會是 `buildspec.yml`，並且放置在來源目錄的根目錄中。 您可以覆寫預設的組建規格檔案名稱和位置。例如，您可以： + 對相同儲存庫中的不同組建使用不同的組建規格檔案，例如 `buildspec_debug.yml` 和 `buildspec_release.yml`。 + 在來源目錄根目錄以外的位置儲存組建規格檔案，例如 `config/buildspec.yml`，或儲存在 S3 儲存貯體中。S3 儲存貯體必須與建置專案位於相同的 AWS 區域。使用其 ARN 指定 buildspec 檔案 (例如，`arn:aws:s3:::/buildspec.yml`)。 您只可以為組建專案指定一個組建規格，而不論組建規格檔案的名稱。 若要覆寫預設的組建規格檔案名稱、位置或兩者，請執行下列其中一個動作： + 執行 AWS CLI `create-project`或 `update-project`命令，將 `buildspec`值設定為相對於內建環境變數 值的替代 buildspec 檔案路徑`CODEBUILD_SRC_DIR`。您也可以在 AWS SDKs 中執行與 `create project`操作相同的操作。如需詳細資訊，請參閱 [建立組建專案](create-project.md) 或 [變更建置專案設定](change-project.md) 。 + 執行 AWS CLI `start-build`命令，將 `buildspecOverride`值設定為相對於內建環境變數 值的替代 buildspec 檔案路徑`CODEBUILD_SRC_DIR`。您也可以在 AWS SDKs 中執行與 `start build`操作相同的操作。如需詳細資訊，請參閱[手動執行組建](run-build.md)。 + 在 AWS CloudFormation 範本中，將 資源`Source`中 的 `BuildSpec` 屬性設定為相對於內建環境變數 值的替代 buildspec 檔案`AWS::CodeBuild::Project`路徑`CODEBUILD_SRC_DIR`。如需詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[AWS CodeBuild 專案來源](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-source.html)中的 BuildSpec 屬性。 ## Buildspec 語法 組建規格檔案必須以 [YAML](http://yaml.org/) 格式表達。 如果命令包含 YAML 不支援的字元或字元字串，您必須以引號 (“”) 括住命令。下列命令用引號括起來，因為 YAML 中不允許冒號 (:) 後面跟著空格。命令中的引號被逸出 (\$1")。 ``` "export PACKAGE_NAME=$(cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g')" ``` 組建規格具有下列語法： ``` version: 0.2 run-as: Linux-user-name env: shell: shell-tag variables: key: "value" key: "value" parameter-store: key: "value" key: "value" exported-variables: - variable - variable secrets-manager: key: secret-id:json-key:version-stage:version-id git-credential-helper: no | yes proxy: upload-artifacts: no | yes logs: no | yes batch: fast-fail: false | true # build-list: # build-matrix: # build-graph: # build-fanout: phases: install: run-as: Linux-user-name on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex runtime-versions: runtime: version runtime: version commands: - command - command finally: - command - command pre\$1build: run-as: Linux-user-name on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex commands: - command - command finally: - command - command build: run-as: Linux-user-name on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex commands: - command - command finally: - command - command post\$1build: run-as: Linux-user-name on-failure: ABORT | CONTINUE | RETRY | RETRY-count | RETRY-regex | RETRY-count-regex commands: - command - command finally: - command - command reports: report-group-name-or-arn: files: - location - location base-directory: location discard-paths: no | yes file-format: report-format artifacts: files: - location - location name: artifact-name discard-paths: no | yes base-directory: location exclude-paths: excluded paths enable-symlinks: no | yes s3-prefix: prefix secondary-artifacts: artifactIdentifier: files: - location - location name: secondary-artifact-name discard-paths: no | yes base-directory: location artifactIdentifier: files: - location - location discard-paths: no | yes base-directory: location cache: key: key fallback-keys: - fallback-key - fallback-key action: restore | save paths: - path - path ``` 建置規格包含下列各項： ### version 必要的映射。代表組建規格版本。建議您使用 `0.2`。 **注意** 雖然仍支援版本 0.1，建議您盡可能使用版本 0.2。如需詳細資訊，請參閱[Buildspec 版本](#build-spec-ref-versions)。 ### 執行方式 選用的序列。僅供 Linux 使用者使用。指定在此 buildspec 檔案中執行命令的 Linux 使用者。 會`run-as`授予指定的使用者讀取和執行許可。在 buildspec 檔案上方指定 `run-as` 時，它會全域套用到所有命令。如果您不想為所有 buildspec 檔案命令指定一個使用者，您可以在其中一個 `phases` 區塊中使用 `run-as` 來為階段中的命令指定一個使用者。如果未指定 `run-as`，則會以根使用者身分執行所有命令。 ### env 選用的序列。代表一或多個自訂環境變數的資訊。 **注意** 為了保護敏感資訊，CodeBuild 日誌中會隱藏下列項目： AWS 存取金鑰 IDs。如需詳細資訊，請參閱*AWS Identity and Access Management 《 使用者指南*》中的[管理 IAM 使用者的存取金鑰](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)。 使用參數存放區指定的字串。如需詳細資訊，請參閱《*Amazon EC2 Systems Manager * [Systems Manager 使用者指南》中的 Systems Manager 參數存放區](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html)和 [Systems Manager 參數存放區主控台演練](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-walk.html#sysman-paramstore-console)。 使用 指定的字串 AWS Secrets Manager。如需詳細資訊，請參閱[金鑰管理](security-key-management.md)。 env/**shell** 選用的序列。指定 Linux 或 Windows 作業系統支援的 Shell。 對於 Linux 作業系統，支援的 shell 標籤為： + `bash` + `/bin/sh` 對於 Windows 作業系統，支援的 shell 標籤為： + `powershell.exe` + `cmd.exe` env/**variables** 如果指定 `env`，且您想要以純文字定義自訂環境變數，則為必要。包含 *key*/*value* 純量的映射，其中的每個映射代表純文字的單一自訂環境變數。*key* 為自訂環境變數的名稱，而 *value* 為該變數的值。 我們強烈建議不將敏感值儲存在環境變數中。環境變數可以使用 CodeBuild 主控台和 等工具以純文字顯示 AWS CLI。針對機密值，建議您改為使用 `parameter-store` 或 `secrets-manager` 映射，如本節稍後所述。 任何您設定的環境變數都會取代現有環境變數。例如，如果 Docker 影像已包含名為 `MY_VAR` 且值為 `my_value` 的環境變數，而且您設定名為 `MY_VAR` 且值為 `other_value` 的環境變數，則 `my_value` 會取代為 `other_value`。同樣地，如果 Docker 影像已包含名為 `PATH` 且值為 `/usr/local/sbin:/usr/local/bin` 的環境變數，而且您設定名為 `PATH` 且值為 `$PATH:/usr/share/ant/bin` 的環境變數，則 `/usr/local/sbin:/usr/local/bin` 會取代為文字值 `$PATH:/usr/share/ant/bin`。 請不要設定名稱開頭為 `CODEBUILD_` 的任何環境變數。此字首保留供 內部使用。 如果有多個位置定義同名的環境變數，則會決定值，如下所示： + 開始建置操作呼叫中的值會採用最高優先順序。當您建立建置時，您可以新增或覆寫環境變數。如需詳細資訊，請參閱[手動執行 AWS CodeBuild 組建](run-build.md)。 + 組建專案定義中的值會採用下一個優先順序。當您建立或編輯專案時，您可以在專案層級新增環境變數。如需詳細資訊，請參閱[在 中建立建置專案 AWS CodeBuild](create-project.md)及[在 中變更建置專案設定 AWS CodeBuild](change-project.md)。 + buildspec 宣告中的值會採用最低優先順序。 env/**parameter-store** 如果已指定 ，且您想要擷取存放在 Amazon EC2 Systems Manager 參數存放區中的自訂環境變數`env`，則為必要項目。包含索引*鍵*/*值*純量的映射，其中每個映射代表存放在 Amazon EC2 Systems Manager 參數存放區中的單一自訂環境變數。索引*鍵*是您稍後在建置命令中用來參考此自訂環境變數的名稱，而*值*是存放在 Amazon EC2 Systems Manager 參數存放區中的自訂環境變數名稱。若要存放敏感值，請參閱《*Amazon EC2 Systems Manager 使用者指南*》中的 [Systems Manager 參數存放](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html)區和[逐步解說：建立和測試字串參數 （主控台）](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-console.html)。 若要允許 CodeBuild 擷取存放在 Amazon EC2 Systems Manager 參數存放區中的自訂環境變數，您必須將 `ssm:GetParameters`動作新增至 CodeBuild 服務角色。如需詳細資訊，請參閱[允許 CodeBuild 與其他 AWS 服務互動](setting-up-service-role.md)。 您從 Amazon EC2 Systems Manager 參數存放區擷取的任何環境變數都會取代現有的環境變數。例如，如果 Docker 影像已包含名為 `MY_VAR` 且值為 `my_value` 的環境變數，而且您擷取名為 `MY_VAR` 且值為 `other_value` 的環境變數，則 `my_value` 會取代為 `other_value`。同樣地，如果 Docker 影像已包含名為 `PATH` 且值為 `/usr/local/sbin:/usr/local/bin` 的環境變數，而且您擷取名為 `PATH` 且值為 `$PATH:/usr/share/ant/bin` 的環境變數，則 `/usr/local/sbin:/usr/local/bin` 會取代為文字值 `$PATH:/usr/share/ant/bin`。 請不要存放名稱開頭為 `CODEBUILD_` 的任何環境變數。此字首保留供 內部使用。 如果有多個位置定義同名的環境變數，則會決定值，如下所示： + 開始建置操作呼叫中的值會採用最高優先順序。當您建立建置時，您可以新增或覆寫環境變數。如需詳細資訊，請參閱[手動執行 AWS CodeBuild 組建](run-build.md)。 + 組建專案定義中的值會採用下一個優先順序。當您建立或編輯專案時，您可以在專案層級新增環境變數。如需詳細資訊，請參閱[在 中建立建置專案 AWS CodeBuild](create-project.md)及[在 中變更建置專案設定 AWS CodeBuild](change-project.md)。 + buildspec 宣告中的值會採用最低優先順序。 env/**secrets-manager** 如果您想要擷取存放在 中的自訂環境變數，則為必要項目 AWS Secrets Manager。`reference-key` 使用以下模式指定 Secrets Manager： ``: `:::` ** （必要） 本機環境變數名稱。使用此名稱在建置期間存取 變數。 ** （必要） 做為秘密唯一識別符的名稱或 Amazon Resource Name (ARN)。若要存取您 AWS 帳戶中的秘密，只需要指定秘密名稱。若要存取不同 AWS 帳戶中的秘密，請指定秘密 ARN。 ** （選用） 指定您要擷取其值之 Secrets Manager 金鑰/值對的金鑰名稱。如果您未指定 `json-key`，CodeBuild 會擷取整個秘密文字。 *<版本階段>* （選用） 透過附加至版本的預備標籤，指定您要擷取的秘密版本。預備標籤在輪換程序期間用來追蹤不同版本。如果您使用 `version-stage`，請不要指定 `version-id`。如果您不指定版本階段或版本 ID，則預設會擷取版本階段值為 `AWSCURRENT` 的版本。 ** （選用） 指定您要使用的秘密版本的唯一識別符。如果指定 `version-id`，則不要指定 `version-stage`。如果您不指定版本階段或版本 ID，則預設會擷取版本階段值為 `AWSCURRENT` 的版本。 在下列範例中， `TestSecret`是存放在 Secrets Manager 中的鍵/值對名稱。的金鑰`TestSecret`是 `MY_SECRET_VAR`。您可以在建置期間使用 `LOCAL_SECRET_VAR`名稱存取 變數。 ``` env: secrets-manager: LOCAL_SECRET_VAR: "TestSecret:MY_SECRET_VAR" ``` 如需詳細資訊，請參閱 *AWS Secrets Manager 使用者指南*中的[什麼是 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。 env/**exported-variables** 選用的映射。用於列出您想要匯出的環境變數。在 `exported-variables` 下以獨立行列指定您想要匯出的每個變數的名稱。建置期間您想要匯出的變數必須在容器中提供。您匯出的變數可為環境變數。 匯出的環境變數會與 搭配使用 AWS CodePipeline ，將環境變數從目前的建置階段匯出至管道中的後續階段。如需詳細資訊，請參閱*AWS CodePipeline 《 使用者指南*》中的[使用變數](https://docs.aws.amazon.com//codepipeline/latest/userguide/actions-variables.html)。 建置期間，變數的值在 `install` 階段即開始提供。它可以在`install` 階段開始和 `post_build` 結束之間進行更新。`post_build` 階段結束後，匯出的變數值無法變更。 無法匯出下列項目： + 建置專案中指定的 Amazon EC2 Systems Manager 參數存放區秘密。 + 建置專案中指定的 Secrets Manager 秘密 + 以 `AWS_` 開頭的環境變數。 env/**git-credential-helper** 選用的映射。用於指示 CodeBuild 是否使用其 Git 登入資料協助程式來提供 Git 登入資料。`yes`如果使用的話。否則為 `no` 或未指定。如需詳細資訊，請參閱 Git 網站上的 [gitcredentials](https://git-scm.com/docs/gitcredentials)。 由公有 Git 儲存庫的 Webhook 觸發的建置不支援 `git-credential-helper`。 ### proxy 選用的序列。如果在明確的代理伺服器中執行建置，則用於表示設定。如需詳細資訊，請參閱[在明確代理伺服器中執行 CodeBuild](run-codebuild-in-explicit-proxy-server.md)。 proxy/**upload-artifacts** 選用的映射。如果您想要在明確的代理伺服器中的建置上傳成品，請設為 `yes`。預設值為 `no`。 proxy/**logs** 選用的映射。將明確代理伺服器中建置`yes`的 設定為 ，以建立 CloudWatch 日誌。預設值為 `no`。 ### 階段 必要的序列。代表 CodeBuild 在建置的每個階段執行的命令。 **注意** 在 buildspec 0.1 版中，CodeBuild 會在建置環境中預設 Shell 的個別執行個體中執行每個命令。這表示每個命令會與所有其他命令隔離執行。因此，根據預設，如果單一命令倚賴任何之前命令的狀態 (例如，變更目錄或設定環境變數)，您就無法加以執行。為因應這個限制，我們建議您使用 0.2 版，它可解決這個問題。如果您必須使用組建規格版本 0.1，我們建議使用[建置環境中的 Shell 和命令](build-env-ref-cmd.md)中的方法。 phases/\$1/**run-as** 選用的序列。在建置階段中用來指定可執行其命令的 Linux 使用者。如果也在 buildspec 檔案上方為所有命令全域指定 `run-as`，則階段層級的使用者具有優先權。例如，如果全域`run-as`指定 User-1，而對於只有 `install` 階段的 `run-as` 陳述式指定 User-2，則 中的所有命令會以 User-1 執行，*但* `install`階段中的命令除外，這些命令會以 User-2 執行。 phase/\$1/**on-failure** 選用的序列。指定在階段期間發生失敗時要採取的動作。這可以是下列其中一個值： + `ABORT` - 中止建置。 + `CONTINUE` - 繼續下一個階段。 + `RETRY` - 重試組建最多 3 次，並顯示符合規則表達式 的錯誤訊息`.*`。 + `RETRY-count` - 以符合規則表達式 的錯誤訊息*計數*表示，在指定的次數內重試組建`.*`。請注意，*計數*必須介於 0 到 100 之間。例如，有效值包括 `RETRY-4`和 `RETRY-8`。 + `RETRY-regex` - 重試建置最多 3 次，並使用 *regex* 包含規則運算式以符合指定的錯誤訊息。例如，有效值包括 `Retry-.*Error: Unable to connect to database.*`和 `RETRY-invalid+`。 + `RETRY-count-regex` - 在指定的次數內重試建置，如*計數*所示。請注意，*計數*必須介於 0 到 100 之間。您也可以使用 *regex* 來包含規則表達式，以符合錯誤訊息。例如，有效值包括 `Retry-3-.*connection timed out.*`和 `RETRY-8-invalid+`。 如果未指定此屬性，則失敗程序會遵循轉換階段，如 所示[建置階段轉換](view-build-details-phases.md)。 使用 Lambda 運算或預留容量時，不支援 `on-failure` 屬性。此屬性僅適用於 CodeBuild 提供的 EC2 運算映像。 階段/\$1/**最終** 選用的區塊。`finally` 區塊中指定的命令會在`commands`區塊中的命令之後執行。即使`finally`區塊中的命令失敗，也會執行`commands`區塊中的命令。例如，如果 `commands` 區塊包含三個命令，而第一個命令失敗，CodeBuild 會略過剩餘的兩個命令，並在 `finally`區塊中執行任何命令。當 `commands` 和 `finally` 區塊中的所有命令成功執行時，此階段即成功。如果階段中的任何命令失敗，階段即失敗。 允許的建置階段名稱為： phases/**install** 選用的序列。代表 CodeBuild 在安裝期間執行的任何命令。建議您僅針對在組建環境中安裝套件使用 `install` 階段。例如，您可能會使用此階段來安裝程式碼測試架構，例如 Mocha 或 RSpec。 phases/install/**runtime-versions** 選用的序列。Ubuntu 標準映像 5.0 或更新版本和 Amazon Linux 2 標準映像 4.0 或更新版本支援執行期版本。如已指定，此區段中至少要包含一個執行時間。使用特定版本指定執行時間，主要版本後面接著 `.x` ，以指定 CodeBuild 使用該主要版本搭配其最新的次要版本，或使用`latest`最新的主要和次要版本 （例如 `ruby: 3.2`、 `nodejs: 18.x`或 `java: latest`)。您可以使用數字或環境變數指定執行時間。例如，如果您使用 Amazon Linux 2 標準映像 4.0，則以下指定已安裝 Java 版本 17、python 版本 3 的最新次要版本，以及 Ruby 環境變數中包含的版本。如需詳細資訊，請參閱[CodeBuild 提供的 Docker 映像](build-env-ref-available.md)。 ``` phases: install: runtime-versions: java: corretto8 python: 3.x ruby: "$MY_RUBY_VAR" ``` 您可以在 buildspec 檔案的 `runtime-versions` 區段中指定一或多個執行時間。如果您的執行階段依存於另一個執行時間，您也可以在 buildspec 檔案中指定其相依的執行時間。如果您未在 buildspec 檔案中指定任何執行時間，CodeBuild 會選擇您所使用的映像中可用的預設執行時間。如果您指定一或多個執行時間，CodeBuild 只會使用這些執行時間。如果未指定相依執行時間，CodeBuild 會嘗試為您選擇相依執行時間。 如果未指定執行時間版本，CodeBuild 會使用預設版本。當先前的預設版本達到生命週期結束 (EOL) 時，預設版本可能會變更。為避免意外變更建置環境，建議您在 buildspec 檔案中指定執行時間版本。 如果兩個指定的執行時間發生衝突，則建置會失敗。例如，`android: 29` 和 `java: openjdk11` 相衝突，所以如果指定這兩個，則組建會失敗。 如需可用執行時間的詳細資訊，請參閱 [可用的執行時間](available-runtimes.md)。 如果您指定`runtime-versions`區段並使用 Ubuntu Standard Image 2.0 或更新版本以外的映像，或 Amazon Linux 2 (AL2) 標準映像 1.0 或更新版本，則建置會發出警告 "`Skipping install of runtimes. Runtime version selection is not supported by this build image`."。 phases/install/**commands** 選用的序列。包含一系列純量，其中每個純量代表 CodeBuild 在安裝期間執行的單一命令。CodeBuild 會依序從頭到尾執行每個命令，一次一個。 phases/**pre\$1build** 選用的序列。如果有，代表 CodeBuild 在建置之前執行的命令。例如，您可以使用此階段登入 Amazon ECR，也可以安裝 npm 相依性。 phases/pre\$1build/**commands** 只有在指定 `pre_build` 時才為必要序列。包含一系列純量，其中每個純量代表 CodeBuild 在建置之前執行的單一命令。CodeBuild 會依序從頭到尾執行每個命令，一次一個。 phases/**build** 選用的序列。代表 CodeBuild 在建置期間執行的任何命令。例如，您可能會使用此階段來執行 Mocha、RSpec 或 sbt。 phases/build/**commands** 如果指定 `build` ，則為必要項目。包含一系列純量，其中每個純量代表 CodeBuild 在建置期間執行的單一命令。CodeBuild 會依序從頭到尾執行每個命令，一次一個。 phases/**post\$1build** 選用的序列。如果有，代表 CodeBuild 在建置之後執行的命令。例如，您可以使用 Maven 將建置成品封裝到 JAR 或 WAR 檔案中，也可以將 Docker 映像推送到 Amazon ECR。然後，您可以透過 Amazon SNS 傳送建置通知。 phases/post\$1build/**commands** 如果指定 `post_build` ，則為必要項目。包含一系列純量，其中每個純量代表 CodeBuild 在建置之後執行的單一命令。CodeBuild 從頭到尾依序執行每個命令，一次一個。 ### 報告 **report-group-name-or-arn** 選用的序列。指定傳送報告的目標報告群組。一個專案最多可以擁有五個報告群組。指定現有報告群組的 ARN，或新報告群組的名稱。如果您指定名稱，CodeBuild 會使用專案名稱和您以 格式指定的名稱來建立報告群組`-`。您也可以使用 buildspec 中的環境變數來設定報告群組名稱，例如 `$REPORT_GROUP_NAME`。如需詳細資訊，請參閱[報告群組命名](test-report-group-naming.md)。 reports//**files** 必要的序列。代表包含由建立產生之測試結果原始資料的位置。包含一系列純量，每個純量代表一個單獨的位置，其中 CodeBuild 可以找到相對於原始建置位置的測試檔案，或者，如果設定，則為 `base-directory`。位置可能包括下列： + 單一檔案 (例如，`my-test-report-file.json`)。 + 子目錄中的單一檔案 (例如，`my-subdirectory/my-test-report-file.json` 或 `my-parent-subdirectory/my-subdirectory/my-test-report-file.json`)。 + `'**/*'` 代表遞迴的所有檔案。 + `my-subdirectory/*` 代表名為 *my-subdirectory* 的子目錄中的所有檔案。 + `my-subdirectory/**/*` 代表從名為 *my-subdirectory* 開始的子目錄遞迴的所有檔案。 reports//**file-format** 選用的映射。代表報告檔案格式。如果未指定，則會使用 `JUNITXML`。此值不區分大小寫。可能值為： **測試報告** `CUCUMBERJSON` Cucumber JSON `JUNITXML` JUnit XML `NUNITXML` NUnit XML `NUNIT3XML` NUnit 3 XML `TESTNGXML` TestNG XML `VISUALSTUDIOTRX` Visual Studio TRX **程式碼涵蓋範圍報告** `CLOVERXML` Clover XML `COBERTURAXML` Cobertura XML `JACOCOXML` JaCoCo XML `SIMPLECOV` SimpleCov JSON CodeBuild 接受 [simplecov](https://github.com/simplecov-ruby/simplecov) 產生的 JSON 程式碼涵蓋範圍報告，而不是 [simplecov-json](https://github.com/vicentllongo/simplecov-json)。 reports//**base-directory** 選用的映射。代表一個或多個最上層目錄，相對於原始建置位置，CodeBuild 用來判斷在何處尋找原始測試檔案。 reports//**discard-paths** 選用。指定報告檔案目錄是否在輸出中平面化。如果未指定或包含 `no`，則報告檔案會以完整的目錄結構輸出。如果包含 `yes`，則所有的測試檔案都會放置在相同的輸出目錄中。例如，如果測試結果的路徑是 `com/myapp/mytests/TestResult.xml`，則指定 `yes` 會將此檔案置於 `/TestResult.xml` 中。 ### 成品 選用的序列。代表 CodeBuild 尋找建置輸出的位置，以及 CodeBuild 如何準備上傳到 S3 輸出儲存貯體的相關資訊。例如，如果您正在建置 Docker 映像並將其推送至 Amazon ECR，或者正在對原始程式碼執行單元測試，但未建置它，則不需要此序列。 **注意** Amazon S3 中繼資料具有名為 的 CodeBuild 標頭`x-amz-meta-codebuild-buildarn`，其中包含發佈成品至 Amazon S3 `buildArn`的 CodeBuild 組建的 。`buildArn` 新增 以允許來源追蹤通知，並參考產生成品的建置。 artifacts/**files** 必要的序列。代表包含組建環境中組建輸出成品的位置。包含一系列純量，每個純量代表一個單獨的位置，其中 CodeBuild 可以找到相對於原始組建位置的組建輸出成品，如果設定，則為基本目錄。位置可能包括下列： + 單一檔案 (例如，`my-file.jar`)。 + 子目錄中的單一檔案 (例如，`my-subdirectory/my-file.jar` 或 `my-parent-subdirectory/my-subdirectory/my-file.jar`)。 + `'**/*'` 代表遞迴的所有檔案。 + `my-subdirectory/*` 代表名為 *my-subdirectory* 的子目錄中的所有檔案。 + `my-subdirectory/**/*` 代表從名為 *my-subdirectory* 開始的子目錄遞迴的所有檔案。 當您指定建置輸出成品位置時，CodeBuild 可以在建置環境中找到原始建置位置。您不需要在組建成品輸出位置前方附加原始組建位置的路徑或指定 `./` 之類內容。如果要知道此位置的路徑，您可以在組建期間執行 `echo $CODEBUILD_SRC_DIR` 之類命令。每個組建環境的位置可能稍有不同。 artifacts/**name** 選用名稱。指定組建成品的名稱。當下列其中一項成立時，會使用此名稱。 + 您可以使用 CodeBuild API 來建立組建，並在更新專案、建立專案或啟動組建時，在`ProjectArtifacts`物件上設定 `overrideArtifactName`旗標。 + 您可以使用 CodeBuild 主控台來建立組建、在 buildspec 檔案中指定名稱，並在建立或更新專案時選取**啟用語意版本控制**。如需詳細資訊，請參閱[建立組建專案 (主控台)](create-project.md#create-project-console)。 您可以在組建時計算的組建規格檔案中指定名稱。組建規格檔案中指定的名稱使用 Shell 命令語言。例如，您可以將日期和時間附加到成品名稱，讓它一律是唯一的。唯一成品名稱可防止覆寫成品。如需詳細資訊，請參閱 [Shell 命令語言](http://pubs.opengroup.org/onlinepubs/9699919799/)。 + 這是成品名稱附加了成品建立日期的範例。 ``` version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$(date +%Y-%m-%d) ``` + 這是使用 CodeBuild 環境變數的成品名稱範例。如需詳細資訊，請參閱[建置環境中的環境變數](build-env-ref-env-vars.md)。 ``` version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: myname-$AWS_REGION ``` + 這是成品名稱的範例，其使用 CodeBuild 環境變數，並附加成品的建立日期。 ``` version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: $AWS_REGION-$(date +%Y-%m-%d) ``` 您可以將路徑資訊新增至名稱，以便根據名稱中的路徑將具名成品放置在目錄中。在此範例中，建置成品會放置在 下的輸出中`builds//my-artifacts`。 ``` version: 0.2 phases: build: commands: - rspec HelloWorld_spec.rb artifacts: files: - '**/*' name: builds/$CODEBUILD_BUILD_NUMBER/my-artifacts ``` artifacts/**discard-paths** 選用。指定組建成品目錄是否在輸出中平面化。如果未指定或包含 `no`，則會以完整的目錄結構輸出組建成品。如果包含 `yes`，則所有組建成品都會放置在相同的輸出目錄中。例如，如果組建輸出成品中的文件路徑是 `com/mycompany/app/HelloWorld.java`，則會指定 `yes` 將此文件放置在 `/HelloWorld.java` 中。 artifacts/**base-directory** 選用的映射。代表一個或多個最上層目錄，相對於原始建置位置，CodeBuild 用來判斷要包含在建置輸出成品中的檔案和子目錄。有效值包含： + 單一上層目錄 (例如，`my-directory`)。 + `'my-directory*'` 代表名稱開頭為 `my-directory` 的所有上層目錄。 相符的上層目錄不會包含在組建輸出成品中，只有其檔案和子目錄。 您可以使用 `files` 和 `discard-paths` 以進一步限制包含的檔案和子目錄。例如，針對下列目錄結構： ``` . ├── my-build-1 │ └── my-file-1.txt └── my-build-2 ├── my-file-2.txt └── my-subdirectory └── my-file-3.txt ``` 以及下列 `artifacts` 序列： ``` artifacts: files: - '*/my-file-3.txt' base-directory: my-build-2 ``` 下列子目錄和檔案會包含在組建輸出成品中： ``` . └── my-subdirectory └── my-file-3.txt ``` 當下列 `artifacts` 序列： ``` artifacts: files: - '**/*' base-directory: 'my-build*' discard-paths: yes ``` 下列檔案會包含在組建輸出成品中： ``` . ├── my-file-1.txt ├── my-file-2.txt └── my-file-3.txt ``` artifacts/**exclude-paths** 選用的映射。代表 CodeBuild 將從建置成品中排除的一或多個路徑`base-directory`，相對於 。星號 (`*`) 字元符合不超過資料夾邊界之名稱元件的零個或多個字元。雙星號 (`**`) 會比對所有目錄中名稱元件的零個或多個字元。 exclude-paths 的範例包括下列項目： + 若要從所有目錄排除檔案： `"**/file-name/**/*"` + 若要排除所有點資料夾： `"**/.*/**/*"` + 若要排除所有點檔案： `"**/.*"` artifacts/**enable-symlinks** 選用。如果輸出類型為 `ZIP`，請指定內部符號連結是否保留在 ZIP 檔案中。如果其中包含 `yes`，則來源中的所有內部符號連結都會保留在成品 ZIP 檔案中。 artifacts/**s3 字首** 選用。指定當成品輸出至 Amazon S3 儲存貯體且命名空間類型為 時所使用的字首`BUILD_ID`。使用時，儲存貯體中的輸出路徑為 `//.zip`。 artifacts/**secondary-artifacts** 選用的序列。代表一或多個成品定義，做為成品識別符與成品定義之間的映射。此區塊中的每個成品識別符必須符合專案的 `secondaryArtifacts` 屬性中定義的成品。每個個別的定義具有與以上 `artifacts` 區塊相同的語法。 即使只有定義的次要成品，序列[`artifacts/files`](#build-spec.artifacts.files)也是必要的。 例如，如果您的專案具有以下結構： ``` { "name": "sample-project", "secondaryArtifacts": [ { "type": "S3", "location": "", "artifactIdentifier": "artifact1", "name": "secondary-artifact-name-1" }, { "type": "S3", "location": "", "artifactIdentifier": "artifact2", "name": "secondary-artifact-name-2" } ] } ``` 則您的 buildspec 如下所示： ``` version: 0.2 phases: build: commands: - echo Building... artifacts: files: - '**/*' secondary-artifacts: artifact1: files: - directory/file1 name: secondary-artifact-name-1 artifact2: files: - directory/file2 name: secondary-artifact-name-2 ``` ### 快取 選用的序列。代表 CodeBuild 可以準備檔案以將快取上傳至 S3 快取儲存貯體的相關資訊。如果專案的快取類型為 `No Cache`，則此序列不是必要。 cache/**key** 選用的序列。代表搜尋或還原快取時所使用的主索引鍵。CodeBuild 會完全符合主索引鍵。 以下是 金鑰的範例： ``` key: npm-key-$(codebuild-hash-files package-lock.json) } ``` cache/**fallback-keys** 選用的序列。當無法使用主索引鍵找到快取時，代表循序使用的備用索引鍵清單。最多支援五個備用金鑰，每個金鑰都使用字首搜尋進行比對。如果未提供**金鑰**，則會忽略此序列。 以下是備用金鑰的範例： ``` fallback-keys: - npm-key-$(codebuild-hash-files package-lock.json) } - npm-key- - npm- ``` cache/**action** 選用的序列。指定要在快取上執行的動作。有效值包含： + `restore` 只會還原快取，而不會儲存更新。 + `save` 只會儲存快取，而不會還原先前的版本。 如果未提供任何值，CodeBuild 會預設為同時執行還原和儲存。 cache/**paths** 必要的序列。代表快取的位置。包含一系列純量，每個純量代表一個單獨的位置，其中 CodeBuild 可以找到相對於原始組建位置的組建輸出成品，如果設定，則為基本目錄。位置可能包括下列： + 單一檔案 (例如，`my-file.jar`)。 + 子目錄中的單一檔案 (例如，`my-subdirectory/my-file.jar` 或 `my-parent-subdirectory/my-subdirectory/my-file.jar`)。 + `'**/*'` 代表遞迴的所有檔案。 + `my-subdirectory/*` 代表名為 *my-subdirectory* 的子目錄中的所有檔案。 + `my-subdirectory/**/*` 代表從名為 *my-subdirectory* 開始的子目錄遞迴的所有檔案。 **重要** 因為建置規格宣告必須為有效的 YAML，因此建置規格宣告中的間距相當重要。若您組建規格宣告中的空格數無效，組建會立即失敗。您可以使用 YAML 驗證程式來測試您的組建規格宣告是否為有效的 YAML。 如果您在建立或更新組建專案時使用 AWS CLI或 AWS SDKs 宣告 buildspec，則 buildspec 必須是以 YAML 格式表示的單一字串，以及必要的空格和換行逸出字元。下一節提供一個範例。 如果您使用 CodeBuild 或 AWS CodePipeline 主控台而非 buildspec.yml 檔案，您只能插入 `build`階段的命令。不要使用前述語法，您應該在單一行中列出要在組建階段期間執行的所有命令。針對多個命令，以 `&&` 區隔每個命令 (例如，`mvn test && mvn package`)。 您可以使用 CodeBuild 或 CodePipeline 主控台來指定組建環境中組建輸出成品的位置，而非 buildspec.yml 檔案。不要使用前述語法，而是應該在單一行中列出所有位置。針對多個位置，以逗號區隔每個位置 (例如，`buildspec.yml, target/my-app.jar`)。 ## Buildspec 範例 以下是 buildspec.yml 檔案的範例。 ``` version: 0.2 env: variables: JAVA_HOME: "/usr/lib/jvm/java-8-openjdk-amd64" parameter-store: LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword phases: install: commands: - echo Entered the install phase... - apt-get update -y - apt-get install -y maven finally: - echo This always runs even if the update or install command fails pre_build: commands: - echo Entered the pre_build phase... - docker login -u User -p $LOGIN_PASSWORD finally: - echo This always runs even if the login command fails build: commands: - echo Entered the build phase... - echo Build started on `date` - mvn install finally: - echo This always runs even if the install command fails post_build: commands: - echo Entered the post_build phase... - echo Build completed on `date` reports: arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1: files: - "**/*" base-directory: 'target/tests/reports' discard-paths: no reportGroupCucumberJson: files: - 'cucumber/target/cucumber-tests.xml' discard-paths: yes file-format: CUCUMBERJSON # default is JUNITXML artifacts: files: - target/messageUtil-1.0.jar discard-paths: yes secondary-artifacts: artifact1: files: - target/artifact-1.0.jar discard-paths: yes artifact2: files: - target/artifact-2.0.jar discard-paths: yes cache: paths: - '/root/.m2/**/*' ``` 以下是上述 buildspec 的範例，以單一字串表示，可與 AWS CLI或 AWS SDKs搭配使用。 ``` "version: 0.2\n\nenv:\n variables:\n JAVA_HOME: \"/usr/lib/jvm/java-8-openjdk-amd64\\"\n parameter-store:\n LOGIN_PASSWORD: /CodeBuild/dockerLoginPassword\n phases:\n\n install:\n commands:\n - echo Entered the install phase...\n - apt-get update -y\n - apt-get install -y maven\n finally:\n - echo This always runs even if the update or install command fails \n pre_build:\n commands:\n - echo Entered the pre_build phase...\n - docker login -u User -p $LOGIN_PASSWORD\n finally:\n - echo This always runs even if the login command fails \n build:\n commands:\n - echo Entered the build phase...\n - echo Build started on `date`\n - mvn install\n finally:\n - echo This always runs even if the install command fails\n post_build:\n commands:\n - echo Entered the post_build phase...\n - echo Build completed on `date`\n\n reports:\n reportGroupJunitXml:\n files:\n - \"**/*\"\n base-directory: 'target/tests/reports'\n discard-paths: false\n reportGroupCucumberJson:\n files:\n - 'cucumber/target/cucumber-tests.xml'\n file-format: CUCUMBERJSON\n\nartifacts:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n secondary-artifacts:\n artifact1:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n artifact2:\n files:\n - target/messageUtil-1.0.jar\n discard-paths: yes\n cache:\n paths:\n - '/root/.m2/**/*'" ``` 以下是 `build`階段中的命令範例，可與 CodeBuild 或 CodePipeline 主控台搭配使用。 ``` echo Build started on `date` && mvn install ``` 在這些範例中： + 純文字的自訂環境變數，已設定 `JAVA_HOME` 的金鑰和 `/usr/lib/jvm/java-8-openjdk-amd64` 的值。 + `dockerLoginPassword` 您儲存在 Amazon EC2 Systems Manager 參數存放區中名為 的自訂環境變數，稍後會在建置命令中使用金鑰 進行參考`LOGIN_PASSWORD`。 + 您無法變更這些組建階段名稱。在此範例中執行的命令為 `apt-get update -y`和 `apt-get install -y maven`（安裝 Apache Maven)、 `mvn install` （將原始程式碼編譯、測試和封裝為建置輸出成品，並在其內部儲存庫中安裝建置輸出成品）、 `docker login`（使用對應於`dockerLoginPassword`您在 Amazon EC2 Systems Manager 參數存放區中設定之自訂環境變數值的密碼登入 Docker) 和數個`echo`命令。此處包含這些`echo`命令，以顯示 CodeBuild 如何執行命令及其執行順序。 + `files` 代表要上傳至組建輸出位置的檔案。在此範例中，CodeBuild 會上傳單一檔案 `messageUtil-1.0.jar`。您可以在組建環境中名為 `target` 的相對目錄中找到 `messageUtil-1.0.jar` 檔案。因為已指定 `discard-paths: yes`，系統會直接上傳 `messageUtil-1.0.jar` (並且不會上傳到中繼 `target` 目錄)。檔案名稱 (`messageUtil-1.0.jar`) 及相對目錄名稱 (`target`) 是以 Apache Maven 建立及存放組建輸出成品的方式為基礎，僅適用於此範例。在您自己的案例中，檔案名稱及目錄可能會有所不同。 + `reports` 代表在建置期間產生報告的兩個報告群組： + `arn:aws:codebuild:your-region:your-aws-account-id:report-group/report-group-name-1` 指定報告群組的 ARN。以測試框架產生的測試結果位於 `target/tests/reports` 目錄。檔案格式為 `JunitXml`，且路徑不會從包含測試結果的檔案移除。 + `reportGroupCucumberJson` 指定新的報告群組。如果專案的名稱為 `my-project`，則會在組件執行時會建立名稱為 `my-project-reportGroupCucumberJson` 的報告群組。以測試框架產生的測試結果位於 `cucumber/target/cucumber-tests.xml`。測試檔案格式為 `CucumberJson`，且路徑不會從包含測試結果的檔案移除。 ## Buildspec 版本 下表列出組建規格版本與版本之間的變更。 | 版本 | 變更 | | --- | --- | | 0.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/build-spec-ref.html) | | 0.1 | 這是組建規格格式的初始定義。 | # 批次建置 buildspec 參考 本主題包含批次建置屬性的 buildspec 參考。 ## 批次 選用的映射。專案的批次建置設定。 批次/**快速失敗** 選用。指定一或多個建置任務失敗時批次建置的行為。 `false` 預設值。所有執行中的組建都會完成。 `true` 當其中一個組建任務失敗時，所有執行中的組建都會停止。 根據預設，所有批次建置任務都會使用 buildspec 檔案中指定的建置設定執行`phases`，例如 `env`和 。您可以在 `batch//buildspec` 參數中指定不同的`env`值或不同的 buildspec 檔案，以覆寫預設建置設定。 `batch` 屬性的內容會根據指定的批次建置類型而有所不同。可能的批次建置類型包括： + [`batch/build-graph`](#build-spec.batch.build-graph) + [`batch/build-list`](#build-spec.batch.build-list) + [`batch/build-matrix`](#build-spec.batch.build-matrix) + [`batch/build-fanout`](#build-spec.batch.build-fanout) ## `batch/build-graph` 定義*建置圖表*。建置圖表定義一組任務，這些任務對批次中的其他任務具有相依性。如需詳細資訊，請參閱[組建圖表](batch-build.md#batch_build_graph)。 此元素包含建置任務的陣列。每個建置任務都包含下列屬性。 **識別符** 必要。任務的識別符。 **buildspec** 選用。用於此任務的 buildspec 檔案路徑和檔案名稱。如果未指定此參數，則會使用目前的 buildspec 檔案。 **除錯工作階段** 選用。布林值，指出是否為此批次建置啟用工作階段偵錯。如需工作階段偵錯的詳細資訊，請參閱 [使用 Session Manager 偵錯組建](session-manager.md)。 `false` 工作階段偵錯已停用。 `true` 工作階段偵錯已啟用。 **依存項目** 選用。此任務所依賴的任務識別符陣列。直到這些任務完成之前，此任務將不會執行。 **env** 選用。任務的建置環境會覆寫 。這可以包含下列屬性： **運算類型** 用於任務的運算類型識別符。如需可能的值[建置環境運算模式和類型](build-env-ref-compute-types.md)，請參閱 中的 **computeType**。 **機群** 用於任務的機群識別符。如需更多資訊，請參閱[在預留容量機群上執行組建](fleets.md)。 **映像** 用於任務的映像識別符。如需可能的值[CodeBuild 提供的 Docker 映像](build-env-ref-available.md)，請參閱 中的**影像識別符**。 **特權模式** 布林值，指出是否要在 Docker 容器內執行 Docker 協助程式。`true` 只有在建置專案用於建置 Docker 映像時，才將 設定為 。否則，嘗試與 Docker 協助程式互動的組建會失敗。預設設定為 `false`。 **type** 用於任務的環境類型識別符。如需可能的值[建置環境運算模式和類型](build-env-ref-compute-types.md)，請參閱 中的**環境類型**。 **變數** 將出現在建置環境中的環境變數。如需更多資訊，請參閱[env/variables](build-spec-ref.md#build-spec.env.variables)。 請注意，**運算類型**和**機群**無法在單一組建的相同識別符中提供。 **ignore-failure** 選用。布林值，指出是否可以忽略此建置任務的失敗。 `false` 預設值。如果此建置任務失敗，批次建置將會失敗。 `true` 如果此建置任務失敗，批次建置仍然可以成功。 以下是組建圖表 buildspec 項目的範例： ``` batch: fast-fail: false build-graph: - identifier: build1 env: variables: BUILD_ID: build1 ignore-failure: false - identifier: build2 buildspec: build2.yml env: variables: BUILD_ID: build2 depend-on: - build1 - identifier: build3 env: variables: BUILD_ID: build3 depend-on: - build2 - identifier: build4 env: compute-type: ARM_LAMBDA_1GB - identifier: build5 env: fleet: fleet_name ``` ## `batch/build-list` 定義*建置清單*。建置清單用於定義平行執行的許多任務。如需詳細資訊，請參閱[組建清單](batch-build.md#batch_build_list)。 此元素包含建置任務的陣列。每個建置任務都包含下列屬性。 **識別符** 必要。任務的識別符。 **buildspec** 選用。用於此任務的 buildspec 檔案路徑和檔案名稱。如果未指定此參數，則會使用目前的 buildspec 檔案。 **除錯工作階段** 選用。布林值，指出是否為此批次建置啟用工作階段偵錯。如需工作階段偵錯的詳細資訊，請參閱 [使用 Session Manager 偵錯組建](session-manager.md)。 `false` 工作階段偵錯已停用。 `true` 工作階段偵錯已啟用。 **env** 選用。任務的建置環境會覆寫 。這可以包含下列屬性： **運算類型** 用於任務的運算類型識別符。如需可能的值[建置環境運算模式和類型](build-env-ref-compute-types.md)，請參閱中的 **computeType**。 **機群** 用於任務的機群識別符。如需更多資訊，請參閱[在預留容量機群上執行組建](fleets.md)。 **映像** 用於任務的映像識別符。如需可能的值[CodeBuild 提供的 Docker 映像](build-env-ref-available.md)，請參閱 中的**影像識別符**。 **特權模式** 布林值，指出是否要在 Docker 容器內執行 Docker 協助程式。`true` 只有在建置專案用於建置 Docker 映像時，才將 設定為 。否則，嘗試與 Docker 協助程式互動的組建會失敗。預設設定為 `false`。 **type** 用於任務的環境類型識別符。如需可能的值[建置環境運算模式和類型](build-env-ref-compute-types.md)，請參閱 中的**環境類型**。 **變數** 將出現在建置環境中的環境變數。如需更多資訊，請參閱[env/variables](build-spec-ref.md#build-spec.env.variables)。 請注意，**運算類型**和**機群**無法在單一組建的相同識別符中提供。 **ignore-failure** 選用。布林值，指出是否可以忽略此建置任務的失敗。 `false` 預設值。如果此建置任務失敗，批次建置將會失敗。 `true` 如果此建置任務失敗，批次建置仍然可以成功。 以下是組建清單 buildspec 項目的範例： ``` batch: fast-fail: false build-list: - identifier: build1 env: variables: BUILD_ID: build1 ignore-failure: false - identifier: build2 buildspec: build2.yml env: variables: BUILD_ID: build2 ignore-failure: true - identifier: build3 env: compute-type: ARM_LAMBDA_1GB - identifier: build4 env: fleet: fleet_name - identifier: build5 env: compute-type: GENERAL_LINUX_XLAGRE ``` ## `batch/build-matrix` 定義*建置矩陣*。建置矩陣會定義具有平行執行之不同組態的任務。CodeBuild 會為每個可能的組態組合建立個別的組建。如需詳細資訊，請參閱[建置矩陣](batch-build.md#batch_build_matrix)。 **靜態** 靜態屬性會套用至所有建置任務。 **ignore-failure** 選用。布林值，指出是否可以忽略此建置任務的失敗。 `false` 預設值。如果此建置任務失敗，批次建置將會失敗。 `true` 如果此建置任務失敗，批次建置仍然可以成功。 **env** 選用。建置環境會覆寫所有任務。 **特權模式** 布林值，指出是否要在 Docker 容器內執行 Docker 協助程式。`true` 只有在建置專案用於建置 Docker 映像時，才將 設定為 。否則，嘗試與 Docker 協助程式互動的組建會失敗。預設設定為 `false`。 **type** 用於任務的環境類型識別符。如需可能的值[建置環境運算模式和類型](build-env-ref-compute-types.md)，請參閱 中的**環境類型**。 **動態** 動態屬性定義建置矩陣。 **buildspec** 選用。陣列，其中包含用於這些任務之 buildspec 檔案的路徑和檔案名稱。如果未指定此參數，則會使用目前的 buildspec 檔案。 **env** 選用。建置環境會覆寫這些任務。 **運算類型** 陣列，其中包含用於這些任務的運算類型識別符。如需可能的值[建置環境運算模式和類型](build-env-ref-compute-types.md)，請參閱中的 **computeType**。 **映像** 陣列，其中包含用於這些任務的影像識別符。如需可能的值[CodeBuild 提供的 Docker 映像](build-env-ref-available.md)，請參閱 中的**影像識別符**。 **變數** 陣列，其中包含這些任務在建置環境中存在的環境變數。如需更多資訊，請參閱[env/variables](build-spec-ref.md#build-spec.env.variables)。 以下是組建矩陣 buildspec 項目的範例： ``` batch: build-matrix: static: ignore-failure: false dynamic: buildspec: - matrix1.yml - matrix2.yml env: variables: MY_VAR: - VALUE1 - VALUE2 - VALUE3 ``` 如需詳細資訊，請參閱[建置矩陣](batch-build.md#batch_build_matrix)。 ## `batch/build-fanout` 定義*建置散發*。建置散發用於定義任務，該任務會分割成多個平行執行的建置。如需詳細資訊，請參閱[在批次建置中執行平行測試](parallel-test.md)。 此元素包含可分割為多個組建的組建任務。`build-fanout` 區段包含下列屬性。 **平行處理** 必要。將平行執行測試的組建數目。 **ignore-failure** 選用。布林值，指出是否可以忽略任何散發建置任務中的失敗。此 **ignore-failure** 值將套用至所有散發組建。 **false** 預設值。如果任何散發建置任務失敗，批次建置將會失敗。 **true** 如果任何散發建置任務失敗，批次建置仍然可以成功。 以下是建置散發 buildspec 項目的範例： ``` version: 0.2 batch: fast-fail: false build-fanout: parallelism: 5 ignore-failure: false phases: install: commands: - npm install build: commands: - mkdir -p test-results - cd test-results - | codebuild-tests-run \ --test-command 'npx jest --runInBand --coverage' \ --files-search "codebuild-glob-search '**/test/**/*.test.js'" \ --sharding-strategy 'equal-distribution' ``` 如需詳細資訊，請參閱 [建置分發](batch-build.md#batch_build_fanout) 和 [使用 `codebuild-tests-run` CLI 命令](parallel-test-tests-run.md)。