本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

CodeBuild 的建置規格參考

本主題提供關於建置規格 (Buildspec) 檔案的重要參考資訊。buildspec 是組建命令和相關設定的集合，採用 YAML 格式，CodeBuild 用於執行組建。您可以在原始程式碼中包含 buildspec，也可以在建立建置專案時定義 buildspec。如需組建規格運作方式的詳細資訊，請參閱 CodeBuild 運作方式。

Buildspec 檔案名稱和儲存位置

若您隨著來源碼併入組建規格，依預設，組建規格檔案的名稱會是 buildspec.yml，並且放置在來源目錄的根目錄中。

您可以覆寫預設的組建規格檔案名稱和位置。例如，您可以：

您只可以為組建專案指定一個組建規格，而不論組建規格檔案的名稱。

若要覆寫預設的組建規格檔案名稱、位置或兩者，請執行下列其中一個動作：

Buildspec 語法

組建規格檔案必須以 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:
  # 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_build:
    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_build:
    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:
  paths:
    - path
    - path

建置規格包含下列各項：

version

必要的映射。代表組建規格版本。建議您使用 0.2。

執行方式

選用的序列。僅供 Linux 使用者使用。指定在此 buildspec 檔案中執行命令的 Linux 使用者。 會run-as授予指定的使用者讀取和執行許可。在 buildspec 檔案上方指定 run-as 時，它會全域套用到所有命令。如果您不想為所有 buildspec 檔案命令指定一個使用者，您可以在其中一個 phases 區塊中使用 run-as 來為階段中的命令指定一個使用者。如果未指定 run-as，則會以根使用者身分執行所有命令。

env

選用的序列。代表一或多個自訂環境變數的資訊。

proxy

選用的序列。如果在明確的代理伺服器中執行建置，則用於表示設定。如需詳細資訊，請參閱 在明確的代理伺服器 CodeBuild 中執行。

階段

必要的序列。代表 CodeBuild 在建置的每個階段執行的命令。

允許的建置階段名稱為：

報告

成品

選用的序列。代表 CodeBuild 可在何處找到建置輸出，以及 CodeBuild 如何準備將其上傳至 S3 輸出儲存貯體的資訊。例如，如果您正在建置 Docker 映像並將其推送至 Amazon ECR，或者正在對原始程式碼執行單位測試，但沒有建置它，則不需要此序列。

快取

選用的序列。代表 CodeBuild 可以準備檔案以將快取上傳至 S3 快取儲存貯體的資訊。如果專案的快取類型為 No Cache，則此序列不是必要。

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

在這些範例中：

Buildspec 版本

下表列出組建規格版本與版本之間的變更。