适用于 CodeBuild 的构建规范参考

此主题提供有关构建规范文件的重要参考信息。构建规范 是构建命令和相关设置的集合，采用 YAML 格式，由 CodeBuild 用来运行构建任务。您可以在源代码中包含构建规范，也可以在创建构建项目时定义构建规范。有关构建规范工作原理的信息，请参阅CodeBuild的工作原理。

主题

构建规范文件名称和存储位置

如果您在源代码中包含构建规范，则默认情况下，构建规范文件必须命名为 buildspec.yml 且放置在源目录的根目录中。

可以覆盖默认构建规范文件名和位置。譬如，您可以：

对同一存储库中的不同构建使用不同的构建规范文件，如 buildspec_debug.yml 和 buildspec_release.yml。
将构建规范文件存储在源目录的根目录之外的位置，如 config/buildspec.yml 或 S3 存储桶。S3 存储桶必须与您的构建项目位于同一 Amazon 区域。使用其 ARN 指定构建规范文件（例如，arn:aws:s3:::<my-codebuild-sample2>/buildspec.yml）。

您可以只为构建项目指定一个构建规范，而不管构建规范文件的名称如何。

要覆盖默认构建规范文件名、默认位置或这两者，执行下列操作之一：

运行 Amazon CLI create-project 或 update-project 命令，将 buildspec 值设置为备用构建规范文件的路径（相对于内置环境变量 CODEBUILD_SRC_DIR 的值）。您还可以在 Amazon 开发工具包中执行与 create project 操作等效的操作。有关更多信息，请参阅创建构建项目或更改构建项目的设置。
运行 Amazon CLI start-build 命令，将 buildspecOverride 值设置为备用构建规范文件的路径（相对于内置环境变量 CODEBUILD_SRC_DIR 的值）。您还可以在 Amazon 开发工具包中执行与 start build 操作等效的操作。有关更多信息，请参阅运行构建：
在 Amazon CloudFormation 模板中，将类型为 AWS::CodeBuild::Project 的资源中 Source 的 BuildSpec 属性设置为备用构建规范文件的路径（相对于内置环境变量 CODEBUILD_SRC_DIR 的值）。有关更多信息，请参阅BuildSpec房产在Amazon CodeBuild项目来源在Amazon CloudFormation用户指南。

构建规范语法

构建规范文件必须以 YAML 格式表示。

如果命令包含 YAML 不支持的字符或字符串，则必须用引号 ("") 将命令括起来。以下命令用引号括起来，因为在 YAML 中不允许使用冒号 (:) 后跟空格。命令中的引号会被转义 (\")。


"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:
        
phases:
  install:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    runtime-versions:
      runtime: version
      runtime: version
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  pre_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
  post_build:
    run-as: Linux-user-name
    on-failure: ABORT | CONTINUE
    commands:
      - command
      - command
    finally:
      - command
      - command
    # steps:
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:
  paths:
    - path
    - path

构建规范包含以下内容：

version

必需的映射。表示构建规范版本。建议使用 0.2。

注意

虽然仍支持版本 0.1，但建议尽可能使用版本 0.2。有关更多信息，请参阅构建规范版本：

run-as

可选的序列。仅适用于 Linux 用户。指定在此 buildspec 文件中运行命令的 Linux 用户。run-as授予指定用户读取和运行权限。当您在构建规范文件的顶部指定 run-as 时，它将全局应用于所有命令。如果您不希望为所有构建规范文件命令指定一个用户，可以通过在其中一个 phases 语句块中使用 run-as，为一个阶段中的命令指定一个用户。如果未指定 run-as，则所有命令都将以根用户身份运行。

env

可选的序列。表示一个或多个自定义环境变量的信息。

注意

为了保护敏感信息，CodeBuild 日志中隐藏以下内容：

Amazon 访问密钥 ID。有关更多信息，请参阅管理 IAM 用户的访问密钥在Amazon Identity and Access Management用户指南。
使用参数存储指定的字符串。有关更多信息，请参阅系统管理器参数存储和系统管理器参数存储控制台演练在亚马逊 EC2 系统管理器用户指南。
使用指定的字符串Amazon Secrets Manager。有关更多信息，请参阅密钥管理：

env/贝壳

可选的序列。指定 Linux 或 Windows 操作系统支持的外壳。

对于 Linux 操作系统，支持的外壳标签有：

bash
/bin/sh

对于 Windows 操作系统，支持的外壳标签有：

powershell.exe
cmd.exe

env/variables

在指定了 env 并且您希望定义纯文本格式的自定义环境变量时必需。包含 key/value 标量的映射，其中每个映射表示一个纯文本形式的自定义环境变量。key 是自定义环境变量的名称，value 是该变量的值。

重要

我们强烈不鼓励在环境变量中存储敏感值。使用 CodeBuild 控制台和 Amazon 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_ 开头的任何环境变量。此前缀是专为内部使用预留的。

如果具有相同名称的环境变量在多处都有定义，则应按照如下方式确定其值：

构建操作调用开始时的值优先级最高。您可以在创建构建时添加或覆盖环境变量。有关更多信息，请参阅在 Amazon CodeBuild 中运行构建：
构建项目定义中的值优先级次之。您可以在创建或编辑项目时在项目级别添加环境变量。有关更多信息，请参阅在 Amazon CodeBuild 中创建构建项目和更改 Amazon CodeBuild 中构建项目的设置。
构建规范声明中的值优先级最低。

env/parameter-store

如果是必填项env已指定，并且您想要检索存储在 Amazon EC2 Systems Manager 参数存储中的自定义环境变量。包含的映射为钥匙/价值标量，其中每个映射表示存储在 Amazon EC2 Systems Manager 参数存储中的单个自定义环境变量。钥匙是您稍后在构建命令中用来引用此自定义环境变量的名称，以及价值是存储在 Amazon EC2 系统管理器参数存储中的自定义环境变量的名称。要存储敏感值，请参见系统管理器参数存储和演练：创建和测试字符串参数（控制台）在亚马逊 EC2 系统管理器用户指南。

重要

要允许CodeBuild要检索存储在 Amazon EC2 Systems Manager 参数存储中的自定义环境变量，您必须添加ssm:GetParameters对你采取行动CodeBuild服务角色。有关更多信息，请参阅创建 CodeBuild 服务角色：

您从 Amazon EC2 系统管理器参数存储中检索的任何环境变量都会替换现有的环境变量。例如，如果 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_ 开头的任何环境变量。此前缀是专为内部使用预留的。

如果具有相同名称的环境变量在多处都有定义，则应按照如下方式确定其值：

构建操作调用开始时的值优先级最高。您可以在创建构建时添加或覆盖环境变量。有关更多信息，请参阅在 Amazon CodeBuild 中运行构建：
构建项目定义中的值优先级次之。您可以在创建或编辑项目时在项目级别添加环境变量。有关更多信息，请参阅在 Amazon CodeBuild 中创建构建项目和更改 Amazon CodeBuild 中构建项目的设置。
构建规范声明中的值优先级最低。

env/secrets-manager

如果要检索存储在中的自定义环境变量，则为必填项Amazon Secrets Manager。指定凭据管理器reference-key使用以下模式：

<key>: <secret-id>:<json-key>:<version-stage>:<version-id>

<key>: （必需）本地环境变量名称。在生成过程中使用此名称访问变量。
<secret-id>: （必填）用作密钥唯一标识符的名称或亚马逊资源名称 (ARN)。要访问您的 Amazon 账户中的密钥，只需指定密钥名称。要访问其他 Amazon 账户中的密钥，请指定密钥 ARN。
<json-key>: （可选）指定要检索其值的 Secrets Manager 键值对的键名。如果您不指定 json-key，CodeBuild 会索整个密钥文本。
<version-stage>: （可选）通过附加到版本的暂存标签指定要检索的密钥版本。暂存标签用于在轮换过程中跟踪不同版本。如果您使用 version-stage，则不要指定 version-id。如果您不指定版本阶段或版本 ID，则默认设置是检索版本阶段值为 AWSCURRENT 的版本。
<version-id>: （可选）指定要使用的密钥版本的唯一标识符。如果您指定 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"

有关更多信息，请参阅《Amazon Secrets Manager 用户指南》中的什么是 Amazon Secrets Manager。

env/exported-variables

可选的映射。用于列出您要导出的环境变量。在 exported-variables 下的单独行上指定要导出的每个变量的名称。在构建过程中，要导出的变量必须在容器中可用。导出的变量可以是环境变量。

导出的环境变量与Amazon CodePipeline将环境变量从当前构建阶段导出到管道中的后续阶段。有关更多信息，请参阅使用变量在Amazon CodePipeline用户指南。

在构建期间，变量的值从 install 阶段开始可用。可以在 install 阶段开始和 post_build 阶段结束之间更新变量的值。在 post_build 阶段结束后，无法更改导出的变量的值。

注意

无法导出以下项：

Amazon EC2 系统管理器参数存储在构建项目中指定的密钥。
在构建项目中指定的凭据管理器密钥
以 AWS_ 开头的环境变量。

env/git-credential-helper

可选的映射。用于指示 CodeBuild 是否使用其 Git 凭证辅助程序来提供 Git 凭证。如果使用该辅助程序，则为 yes。否则为 no 或未指定。有关更多信息，请参阅 Git 网站上的 gitcredentials。

注意

由 Webhook 触发的公有 Git 存储库的构建不支持 git-credential-helper。

proxy

可选的序列。如果是在显式代理服务器中运行构建，则用于表示设置。有关更多信息，请参阅在显式代理服务器中运行 CodeBuild：

proxy/upload-artifacts: 可选的映射。如果您希望显式代理服务器中的构建来上传构件，请设置为 yes。默认为 no。
proxy/logs: 可选的映射。要使显式代理服务器中的构建创建 CloudWatch 日志，请设置为 yes。默认为 no。

phases

必需的序列。表示 CodeBuild 在构建的各个阶段将运行的命令。

注意

在构建规范版本 0.1 中，CodeBuild 将在构建环境中的默认 Shell 的单独实例中运行每条命令。这表示各个命令独立于其他所有命令而运行。因此，在默认情况下，您无法运行依赖所有上一个命令状态的单个命令 (如更改目录或设置环境变量)。要绕开此限制，建议使用版本 0.2 来解决此问题。如果必须使用构建规范版本 0.1，建议使用构建环境中的 Shell 和命令中的方法。

phases/*/run-as

可选的序列。在构建阶段中使用，以指定运行命令的 Linux 用户。如果还在构建规范文件的顶部为所有命令全局指定了 run-as，则阶段级别用户优先。例如，如果全球run-as指定用户 1，并为install只有 a 阶段run-as语句指定 User-2，然后 buildspec 文件中的所有命令都以 User-1 的身份运行除了中的命令install阶段，以 User-2 的身份运行。

阶段/*/失败时

可选的序列。指定该阶段发生故障时要采取的操作。它可以是以下值之一：

ABORT-中止构建。
CONTINUE-继续下一阶段。

如果未指定此属性，则故障过程将遵循过渡阶段，如中所示构建阶段过渡。

阶段/*/终于

可选的数据块。在 a 中指定的命令finally块是在命令之后运行的commands阻止。中的命令finally即使中有一个命令，区块也会运行commands区块失败。例如，如果 commands 语句块包含三条命令，而第一条命令失败了，则 CodeBuild 会跳过剩下的两条命令来运行 finally 语句块中的任何命令。当 commands 和 finally 语句块中的所有命令都成功运行后，此阶段才算成功。如果某个阶段有任何命令失败，则该阶段失败。

允许的构建阶段名称是：

phases/install

可选的序列。表示 CodeBuild 在安装过程中将运行的命令（如果有）。建议使用仅适用于在构建环境中安装软件包的 install 阶段。例如，您可以使用此阶段来安装代码测试框架 (如 Mocha 或 RSpec)。

phases/install/runtime-versions

可选的序列。Ubuntu 标准映像 5.0 或更高版本以及亚马逊 Linux 2 标准映像 4.0 或更高版本支持运行时版本。如果指定，则本节中必须包含至少一个运行时。使用特定版本指定运行时，使用主版本后面加上.x具体说明这一点CodeBuild使用该主要版本及其最新的次要版本，或者latest使用最新的主要版本和次要版本（例如，ruby: 3.2，nodejs: 18.x，或java: latest)。您可以使用一个数字或一个环境变量来指定运行时。例如，如果您使用亚马逊 Linux 2 标准映像 4.0，则以下内容指定安装了 Java 版本 17、python 版本 3 的最新次要版本以及 Ruby 环境变量中包含的版本。有关更多信息，请参阅CodeBuild 提供的 Docker 映像：


phases:
  install:
    runtime-versions:
      java: corretto8
      python: 3.x
      ruby: "$MY_RUBY_VAR"

您可以在构建规范文件的 runtime-versions 部分中指定一个或多个运行时。如果您的运行时依赖于另一个运行时，您还可以在构建规范文件中指定其依赖运行时。如果您未在构建规范文件中指定任何运行时，CodeBuild 选择在您使用的映像中提供的默认运行时。如果指定一个或多个运行时，则 CodeBuild 仅使用这些运行时。如果未指定依赖运行时，则 CodeBuild 尝试为您选择依赖运行时。

如果两个指定运行时冲突，构建将失败。例如，android: 29 和 java: openjdk11 冲突，因此，如果同时指定了这两项，构建将失败。

有关可用运行时的更多信息，请参见可用运行时。

注意

如果你指定runtime-versions部分并使用 Ubuntu 标准映像 2.0 或更高版本或亚马逊 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_build

可选的序列。表示 CodeBuild 在构建之前将运行的命令（如果有）。例如，您可以使用此阶段登录 Amazon ECR，也可以安装 npm 依赖项。

phases/pre_build/commands: 如果指定 pre_build，则为必需的序列。包含一系列标量，其中各个标量表示 CodeBuild 将在生成前运行的单个命令。CodeBuild 按照列出的顺序从开始到结束一次运行一个命令。

phases/build

可选的序列。表示 CodeBuild 在生成过程中将运行的命令（如果有）。例如，您可以使用此阶段运行 Mocha、RSpec 或 sbt。

phases/build/commands: 如果是必填项build已指定。包含一系列标量，其中各个标量表示 CodeBuild 将在生成过程中运行的单个命令。CodeBuild 按照列出的顺序从开始到结束一次运行一个命令。

phases/post_build

可选的序列。表示 CodeBuild 在生成后将运行的命令（如果有）。例如，您可以使用 Maven 将构建工件打包到 JAR 或 WAR 文件中，也可以将 Docker 映像推送到 Amazon ECR 中。然后，您可以通过亚马逊 SNS 发送构建通知。

phases/post_build/commands: 如果是必填项post_build已指定。包含一系列标量，其中各个标量表示 CodeBuild 将在生成后运行的单个命令。CodeBuild 按照列出的顺序从开始到结束一次运行一个命令。

报告

report-group-name-or-arn

可选的序列。指定报告将发送到的报告组。一个项目最多可具有五个报告组。指定现有报告组的 ARN 或新报告组的名称。如果您指定一个名称，CodeBuild 将使用项目名称和您指定的格式为 <project-name>-<report-group-name> 的名称创建一个报告组。有关更多信息，请参阅报告组命名：

reports/<report-group>/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/<report-group>/file-format

可选的映射。表示报告文件格式。如果未指定，则使用 JUNITXML。此值不区分大小写。可能的值有：

测试报告

CUCUMBERJSON: Cucumber JSON
JUNITXML: JUnit XML
NUNITXML: NUnit XML
NUNIT3XML: nUnit 3 XML
TESTNGXML: TestNG XML
VISUALSTUDIOTRX: Visual Studio TRX

代码覆盖率报告

CLOVERXML: 三叶草 XML
COBERTURAXML: XML 覆盖范围
JACOCOXML: JaCoCoXML
SIMPLECOV: SimpleCovJSON

注意
CodeBuild接受由生成的 JSON 代码覆盖率报告simplecov，不是simplecov-js。

reports/<report-group>/base-directory

可选的映射。表示一个或多个顶级目录（相对于原始构建位置），CodeBuild 使用该目录确定在何处查找原始测试文件。

reports/<report-group>/discard-paths

可选。指定是否在输出中展平报告文件目录。如果未指定此项或包含 no，则将输出报告文件，并且其目录结构保持不变。如果此项包含 yes，则将所有测试文件放置在同一个输出目录中。例如，如果测试结果的路径为 com/myapp/mytests/TestResult.xml，指定 yes 会将此文件放置在 /TestResult.xml 中。

人工制品

可选的序列。表示有关 CodeBuild 可在何处查找构建输出以及 CodeBuild 如何进行准备以便将其上传到 S3 输出存储桶的信息。例如，如果您正在构建 Docker 映像并将其推送到 Amazon ECR，或者您正在对源代码运行单元测试但未进行构建，则不需要此序列。

注意

亚马逊 S3 元数据有一个CodeBuild标题名为x-amz-meta-codebuild-buildarn其中包含buildArn的CodeBuild用于将构件发布到亚马逊 S3 的版本。的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

可选的名称。为构建构件指定名称。将在以下任一条件为 true 时使用此名称。

使用 CodeBuild API 创建构建，并于更新项目、创建项目或启动构建后，在 ProjectArtifacts 对象上设置 overrideArtifactName 标记。
使用 CodeBuild 控制台创建您的构建，在构建规范文件中指定名称，并在创建或更新项目时选择 Enable semantic versioning (启用语义版本控制)。有关更多信息，请参阅创建构建项目 (控制台)：

可以在构建规范文件中指定在构建时计算得出的名称。构建规范文件中指定的名称使用 Shell 命令语言。例如，您可以将日期和时间附加到您的项目名称后面，以便它始终是唯一的。构件名称唯一防止覆盖构件。有关更多信息，请参阅 Shell 命令语言。

这是追加有构件创建日期的构件名称的示例。


version: 0.2
phases:
  build:
    commands:
      - rspec HelloWorld_spec.rb
artifacts:
  files:
    - '**/*'
  name: myname-$(date +%Y-%m-%d)

这是使用 CodeBuild 环境变量的构件名称的示例。有关更多信息，请参阅构建环境中的环境变量：


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/<build number>/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

文物/排除路径

可选的映射。代表一条或多条路径，相对于于base-directory，那个CodeBuild将从构建工件中排除。星号 (*) 字符与不跨越文件夹边界的名称组分的零个或多个字符匹配。双星号 (**) 匹配所有目录中名称组件的零个或多个字符。

排除路径的示例包括以下内容：

要从所有目录中排除文件，请执行以下操作："**/file-name/**/*"
要排除所有点状文件夹，请执行以下操作："**/.*/**/*"
要排除所有点文件，请执行以下操作："**/.*"

文物/启用符号链接

可选。如果输出类型是ZIP，指定 ZIP 文件中是否保留内部符号链接。如果这包含yes，源代码中的所有内部符号链接都将保留在工件 ZIP 文件中。

文物/s3 前缀

可选。指定将项目输出到 Amazon S3 存储桶时使用的前缀，命名空间类型为BUILD_ID。使用时，存储桶中的输出路径为<s3-prefix>/<build-id>/<name>.zip。

artifacts/secondary-artifacts

可选的序列。将一个或多个构件定义表示为构件标识符与构件定义之间的映射。此块中的每个构件标识符都必须与项目的 secondaryArtifacts 属性中定义的构件匹配。每个单独的定义与上面的 artifacts 块具有相同的语法。

注意

的artifacts/files序列始终是必需的，即使只定义了次要工件也是如此。

例如，如果项目具有以下结构：


{
  "name": "sample-project",
  "secondaryArtifacts": [
    {
      "type": "S3",
      "location": "<output-bucket1>",
      "artifactIdentifier": "artifact1",
      "name": "secondary-artifact-name-1"
    },
    {
      "type": "S3",
      "location": "<output-bucket2>",
      "artifactIdentifier": "artifact2",
      "name": "secondary-artifact-name-2"
    }
  ]
}

则 Buildpec 如下所示：


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/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。

如果您在创建或更新构建项目时使用 Amazon CLI 或 Amazon 开发工具包声明构建规范，则构建规范必须是以 YAML 格式表示的单个字符串，包括必需的空格和换行转义字符。将在下一部分中提供示例。

如果您使用 CodeBuild 或 Amazon CodePipeline 控制台而不是 buildspec.yml 文件，则您只能插入适合 build 阶段的命令。不要使用前一语法，改为单行列出要在构建阶段运行的所有命令。对于多个命令，使用 && 分开各个命令 (例如 mvn test && mvn package)。

您可以使用 CodeBuild 或 CodePipeline 控制台而不是 buildspec.yml 文件指定构建环境中构建输出项目的位置。您不要使用前一语法，而是要使用单行列出所有位置。对于多个位置，使用逗号分开各个位置 (buildspec.yml, target/my-app.jar)。

构建规范示例

以下是 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/**/*'

以下是上一构建规范的示例，此规范与 Amazon CLI 或 Amazon 开发工具包一起使用并表示为单个字符串。


"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（使用与自定义环境变量值对应的密码登录 DockerdockerLoginPassword你在 Amazon EC2 系统管理器参数存储中设置），还有几个echo命令。此处包含的 echo 命令用于显示 CodeBuild 运行命令的方式以及运行命令的顺序。
files 表示要上传到构建输出位置的文件。在此示例中，CodeBuild 将上传单个文件 messageUtil-1.0.jar。在构建环境中名为 messageUtil-1.0.jar 的相对目录中，可找到 target 文件。由于指定了 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，路径将从包含测试结果的文件中删除。

构建规范版本

下表列出了构建规范版本以及版本间的变化。

版本	更改
0.2	`environment_variables` 已重命名为 `env`。 `plaintext` 已重命名为 `variables`。 `artifacts` 的 `type` 属性已被弃用。在版本 0.1 中，Amazon CodeBuild 将在构建环境内默认 Shell 的单独实例中运行每个构建命令。在版本 0.2 中，CodeBuild 将在构建环境中默认 Shell 的同一实例中运行所有构建命令。
0.1	这是构建规范格式的初始定义。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

计划构建

Batch 构建规范参考