故障診斷 AWS CodeBuild

使用本主題的資訊來協助您查明、診斷和解決問題。若要了解如何記錄和監控 CodeBuild 組建以疑難排解問題，請參閱 日誌記錄和監控。

Apache Maven 建置參考錯誤儲存庫中的成品

問題：當您搭配 AWS CodeBuild提供的 Java 組建環境使用 Maven 時，Maven 會從安全中央 Maven 儲存庫提取組建和外掛程式相依性，網址為 https：//https://repo1.maven.org/maven2。即使組建專案的 pom.xml 檔案明確宣告改用其他位置，還是會發生此情況。

可能原因：CodeBuild 提供的 Java 建置環境包含一個名為 的檔案settings.xml，該檔案預先安裝在建置環境的 /root/.m2目錄中。settings.xml 檔案包含下列宣告，指示 Maven 一律從位於 https://repo1.maven.org/maven2 的安全中央 Maven 儲存庫提取組建和外掛程式相依性。

<settings>
  <activeProfiles>
    <activeProfile>securecentral</activeProfile>
  </activeProfiles>
  <profiles>
    <profile>
      <id>securecentral</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
          <releases>
            <enabled>true</enabled>
          </releases>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
          <releases>
            <enabled>true</enabled>
          </releases>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
</settings>

建議解決方案：執行下列操作：

建置命令預設以 root 身分執行

Issue： AWS CodeBuild 以根使用者身分執行建置命令。即使相關組建映像的 Dockerfile 將 USER 指示設為不同使用者，還是會發生此情況。

原因：根據預設，CodeBuild 會以根使用者身分執行所有建置命令。

建議解決方案：無。

當檔案名稱具有非美國 時，組建可能會失敗。 英文字元

問題：當您執行的組建使用檔案的檔案名稱包含非美國 英文字元 （例如中文字元），建置失敗。

可能原因：建置 提供的環境 AWS CodeBuild ，其預設地區設定設為 POSIX。POSIX地區化設定與 CodeBuild 和包含非美國 的檔案名稱不相容。 英文字元 和 可能會導致相關組建失敗。

建議解決方案：將下列命令新增至 buildspec 檔案的 pre_build 區段。這些命令可讓建置環境使用美式英文 UTF-8 進行當地語系化設定，這更相容於 CodeBuild 和包含非美式的檔案名稱。 英文字元。

以 Ubuntu 為基礎的組建環境：

pre_build:
  commands:
    - export LC_ALL="en_US.UTF-8"
    - locale-gen en_US en_US.UTF-8
    - dpkg-reconfigure -f noninteractive locales

針對以 Amazon Linux 為基礎的建置環境：

pre_build:
  commands:
    - export LC_ALL="en_US.utf8"

從 Amazon EC2 參數存放區取得參數時，組建可能會失敗

問題：當組建嘗試取得存放在 Amazon EC2 參數存放區中的一或多個參數值時，組建會在 DOWNLOAD_SOURCE階段失敗，並顯示錯誤 Parameter does not exist。

可能原因：建置專案依賴的服務角色沒有呼叫 ssm:GetParameters動作的許可，或者建置專案使用由 產生的服務角色 AWS CodeBuild ，並允許呼叫 ssm:GetParameters動作，但參數的名稱不是以 開頭/CodeBuild/。

建議解決方案：

無法存取 CodeBuild 主控台中的分支篩選條件

問題：當您建立或更新 AWS CodeBuild 專案時，主控台中無法使用分支篩選選項。

可能的原因：分支篩選選項已棄用。它已被 Webhook 篩選條件群組取代，該群組可對觸發 CodeBuild 中新建置的 Webhook 事件提供更多控制。

建議的解決方案：若要遷移在 Webhook 篩選條件推出之前建立的分支篩選條件，請使用 HEAD_REF 篩選條件和規則表達式 ^refs/heads/branchName$ 建立 Webhook 篩選群組。例如，如果分支篩選條件規則表達式為 ^branchName$，則您放在 HEAD_REF 篩選條件中已更新的規則表達式為 ^refs/heads/branchName$。如需詳細資訊，請參閱Bitbucket Webhook 事件及篩選 GitHub Webhook 事件 (主控台)。

無法檢視組建成功或失敗

問題：您看不到重試的建置是成功或失敗。

可能的原因：建置狀態的報告選項未啟用。

建議的解決方案：建立或更新 CodeBuild 專案時啟用報告建置狀態。此選項會指示 CodeBuild 在您觸發組建時回報狀態。如需詳細資訊，請參閱 AWS CodeBuild API 參考中的 reportBuildStatus。

未向來源提供者報告建置狀態

問題：允許來源提供者的建置狀態報告之後，例如 GitHub 或 Bitbucket，建置狀態不會更新。

可能原因：與來源提供者相關聯的使用者沒有儲存庫的寫入存取權。

建議的解決方案：若要能夠向來源提供者報告建置狀態，與來源提供者相關聯的使用者必須具有儲存庫的寫入存取權。如果使用者沒有寫入存取權，則無法更新建置狀態。如需詳細資訊，請參閱來源提供者存取。

找不到並選取 Windows Server Core 2019 平台的基礎映像

問題：找不到或選取 Windows Server Core 2019 平台的基礎映像。

可能原因：您使用 AWS 的區域不支援此映像。

建議的解決方案：使用下列 AWS 其中一個支援 Windows Server Core 2019 平台基礎映像的區域：

在 Buildspec 檔案中後來的命令無法辨識先前的命令

問題：Buildspec 檔案中後來的命令無法辨識同一 buildspec 檔案中先前一個或多命令的結果。例如，命令可能設定本機環境變數，但後來執行的命令可能無法取得該本機環境變數的值。

可能原因：在 buildspec 檔案 0.1 版中， AWS CodeBuild 會在建置環境的預設 shell 個別執行個體中執行每個命令。這表示每個命令會與所有其他命令隔離執行。所以，根據預設，如果單一命令倚賴任何先前命令的狀態，則無法執行此命令。

建議的解決方案：我們建議您使用 buildspec 0.2 版，以解決此問題。如果您必須使用 Buildspec 0.1 版，建議使用 Shell 命令鏈結運算子 (例如 Linux 中的 &&)，將多個命令合併成單一命令。或者，在您的原始碼中加進含有多個命令的 shell 指令碼，然後在 buildspec 檔案中從單一命令呼叫該 shell 指令碼。如需詳細資訊，請參閱建置環境中的 Shell 和命令及建置環境中的環境變數。

錯誤：嘗試下載快取時出現「存取遭拒」

問題：在已啟用快取的建置專案上嘗試下載快取時，您收到 Access denied 錯誤。

可能原因：

建議的解決方案：第一次使用時，在更新快取組態之後看到此訊息很正常。如果此錯誤持續發生，對於持有快取的 S3 儲存貯體，您應該檢查服務角色是否有 s3:GetObject 和 s3:PutObject 許可。如需詳細資訊，請參閱《Amazon S3 開發人員指南》中的指定 S3 許可。 Amazon S3

使用自訂建置映像時發生錯誤："BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE"

問題：當您嘗試執行的建置使用自訂建置映像時，建置失敗，發生錯誤 BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE。

錯誤：「完成建置之前，發現建置容器失效。因為記憶體不足，或不支援 Docker 映像，建置容器失效。ErrorCode: 500」

問題：當您嘗試在 中使用 Microsoft Windows 或 Linux 容器時 AWS CodeBuild，此錯誤會在 PROVISIONING 階段發生。

可能原因：

建議解決方案：

執行組建時發生錯誤：「無法連接到 Docker 協助程式」

問題：您的建置失敗，並在建置日誌中收到類似 Cannot connect to the Docker daemon at unix:/var/run/docker.sock. Is the docker daemon running? 錯誤。

可能的原因：您不是在特殊權限模式中執行您的建置。

建議的解決方案：若要修正此錯誤，您必須啟用特殊權限模式，並使用下列指示更新您的 buildspec。

若要在特殊權限模式下執行建置，請依照下列步驟執行：

您也需要在容器內啟動 Docker 協助程式。buildspec 的install階段可能看起來像這樣。

phases:
  install:
    commands:
      - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 &
      - timeout 15 sh -c "until docker info; do echo .; sleep 1; done"

如需 Buildspec 檔案中參考的 OverlayFS 儲存驅動程式的詳細資訊，請參閱 Docker 網站上的使用 OverlayFS 儲存驅動程式。

- timeout -t 15 sh -c "until docker info; do echo .; sleep 1; done"

若要進一步了解如何使用 建置和執行 Docker 映像 AWS CodeBuild，請參閱 CodeBuild 自訂映像範例中的 Docker。

錯誤：建立或更新組建專案時，「CodeBuild 無權執行：sts：AssumeRole」

問題：當您嘗試建立或更新建置專案時，您收到 Code:InvalidInputException, Message:CodeBuild is not authorized to perform: sts:AssumeRole on arn:aws:iam::account-ID:role/service-role-name 錯誤。

可能原因：

建議解決方案：

錯誤：「呼叫 GetBucketAcl 時發生錯誤：儲存貯體擁有者已變更，或服務角色不再有權呼叫 s3:GetBucketAcl」

問題：當您執行建置時，您會收到有關 S3 儲存貯體擁有權和 GetBucketAcl 許可變更的錯誤。

可能原因：您已將 s3:GetBucketAcl和 s3:GetBucketLocation許可新增至 IAM 角色。這些許可會保護您專案的 S3 儲存貯體，並確保只有您可加以存取。新增這些許可之後， S3 儲存貯體的擁有者會變更。

建議的解決方案：確認您是 S3 儲存貯體的擁有者，然後再次將許可新增至 IAM 角色。如需詳細資訊，請參閱安全存取 S3 儲存貯體。

執行建置時發生錯誤：「無法上傳成品：無效的 arn」

問題：當您執行建置時，UPLOAD_ARTIFACTS 建置階段失敗，並出現 Failed to upload artifacts: Invalid arn 錯誤。

可能原因：您的 S3 輸出儲存貯體 （存放其建置輸出的 AWS CodeBuild 儲存貯體） 位於與 CodeBuild 建置專案不同的 AWS 區域。

建議的解決方案：更新組建專案的設定，以指向與組建專案位於相同 AWS 區域的輸出儲存貯體。

錯誤：「Git 複製失敗：無法存取 'your-repository-URL'：SSL 憑證問題：自我簽署憑證」

問題：當您嘗試執行建置專案時，建置失敗並出現此錯誤。

可能的原因：您的來源儲存庫有自我簽署憑證，但您在建置專案中未選擇從 S3 儲存貯體來安裝憑證。

建議解決方案：

執行建置時發生錯誤：「必須使用指定的端點來定址您嘗試存取的儲存貯體」

問題：當您執行建置時，DOWNLOAD_SOURCE 建置階段失敗，並出現 The bucket you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint 錯誤。

可能原因：您的預先建置原始程式碼會存放在 S3 儲存貯體中，且該儲存貯體位於與 AWS CodeBuild 建置專案不同的 AWS 區域中。

建議的解決方案：更新建置專案的設定來指向您預先建置的原始程式碼所在的儲存貯體。請確定儲存貯體與建置專案位於相同的 AWS 區域。

錯誤：「此建置映像需要選取至少一個執行時間版本。」

問題：當您執行建置時，DOWNLOAD_SOURCE 建置階段失敗，並出現 YAML_FILE_ERROR: This build image requires selecting at least one runtime version 錯誤。

可能的原因：您的建置使用 Amazon Linux 2 (AL2) 標準映像版本 1.0 或更新版本，或 Ubuntu 標準映像版本 2.0 或更新版本和未於 buildspec 檔案中指定的執行時間。

建議的解決方案：如果您使用 aws/codebuild/standard:2.0 CodeBuild 受管映像，您必須在 buildspec 檔案的 runtime-versions區段中指定執行時間版本。例如，對於使用 PHP 的專案，您可以使用以下 buildspec 檔案：

version: 0.2

phases:
  install:
    runtime-versions:
        php: 7.3
  build:
    commands:
      - php --version
artifacts:
  files:
    -  README.md

如需詳細資訊，請參閱Specify runtime versions in the buildspec file。

錯誤："QUEUED: INSUFFICIENT_SUBNET"，當建置佇列中的建置失敗時

問題：建置佇列中的建置失敗，錯誤類似 QUEUED: INSUFFICIENT_SUBNET。

可能的原因：針對您 VPC 指定的 IPv4 CIDR 區塊使用預留的 IP 地址。您無法使用每個子網路 CIDR 區塊中的前四個 IP 地址和最後一個 IP 地址，也無法將這些 IP 地址指派給執行個體。例如，在使用 CIDR 區塊 10.0.0.0/24 的子網中，會預留下列五個 IP 地址：

建議的解決方案：檢查您的 VPC 是否使用預留 IP 地址。請將所有預留 IP 地址替換為非預留的 IP 地址。如需詳細資訊，請參閱《Amazon VPC 使用者指南》中的 VPC 和子網路規模調整。

錯誤：「無法下載快取：RequestError: 傳送請求失敗，原因：x509: 無法載入系統根目錄，未提供根目錄」

問題：當您嘗試執行建置專案時，建置失敗並出現此錯誤。

可能的原因：您已在建置專案中設定快取，而使用的 Docker 影像較舊且包含過期的根憑證。

建議的解決方案：更新 AWS CodeBuild 專案中使用的 Docker 映像。如需詳細資訊，請參閱CodeBuild 提供的 Docker 映像。

錯誤：「無法從 S3 下載憑證。AccessDenied」

問題：當您嘗試執行建置專案時，建置失敗並出現此錯誤。

可能原因：

建議解決方案：

錯誤：「找不到登入資料」

問題：當您嘗試執行 AWS CLI、使用 AWS SDK 或呼叫另一個類似的元件做為組建的一部分時，您會收到與 AWS CLI、 AWS SDK 或 元件直接相關的組建錯誤。例如，您可能會收到 Unable to locate credentials 等建置錯誤。

可能原因：

建議解決方案：

在代理伺服器中執行 CodeBuild 時發生 RequestError 逾時錯誤

問題： 您收到類似以下其中一項的 RequestError 錯誤：

可能原因：

建議解決方案：

Bourne Shell (sh) 必須存在於建置映像中

問題：您使用的建置映像不是由 提供 AWS CodeBuild，而且您的建置失敗並顯示訊息 Build container found dead before completing the build。

可能原因：Bourne shell (sh) 不包含在您的建置映像中。CodeBuild sh 需要執行建置命令和指令碼。

建議的解決方案：如果 sh不存在於建置映像中，請務必在啟動任何其他使用映像的建置之前將其包含。(CodeBuild 已包含在其建置映像sh中。)

執行建置時出現警告：「正在略過執行時間的安裝。此建置映像不支援執行時間版本選項」

問題：執行建置時，建置日誌包含此警告。

可能原因：您的建置不會使用 Amazon Linux 2 (AL2) 標準映像的 1.0 版或更新版本，或 Ubuntu 標準映像的 2.0 版或更新版本，而且執行時間會在您 buildspec 檔案中的 runtime-versions區段中指定。

建議的解決方案：確保 buildspec 檔案不包含 runtime-versions 區段。只有在您使用 Amazon Linux 2 (AL2) 標準映像或更新版本，或 Ubuntu 標準映像 2.0 版或更新版本時，才需要runtime-versions本節。

錯誤：開啟 CodeBuild 主控台時「無法驗證 JobWorker 身分」

問題：當您開啟 CodeBuild 主控台時，會顯示「無法驗證 JobWorker 身分」錯誤訊息。

可能原因：用於主控台存取的 IAM 角色具有 標籤jobId做為金鑰。此標籤金鑰保留給 CodeBuild，如果存在，則會導致此錯誤。

建議的解決方案：將任何具有 金鑰的自訂 IAM 角色標籤變更為jobId具有不同的金鑰，例如 jobIdentifier。

組建無法啟動

問題：啟動組建時，您會收到組建無法啟動錯誤訊息。

可能原因：已達到並行建置的數量。

建議的解決方案：等到其他組建完成，或增加專案的並行組建限制，然後再次啟動組建。如需詳細資訊，請參閱專案組態。

在本機快取建置中存取 GitHub 中繼資料

問題：在某些情況下，快取組建中的 .git 目錄是文字檔案，而不是目錄。

可能原因：為組建啟用本機來源快取時，CodeBuild 會為.git目錄建立 gitlink。這表示.git目錄實際上是包含目錄路徑的文字檔案。

建議的解決方案：在所有情況下，請使用下列命令來取得 Git 中繼資料目錄。無論 的格式為何，此命令都可以運作.git：

git rev-parse --git-dir

AccessDenied：報告群組的儲存貯體擁有者不符合 S3 儲存貯體的擁有者...

問題：將測試資料上傳至 Amazon S3 儲存貯體時，CodeBuild 無法將測試資料寫入儲存貯體。

可能原因：

建議解決方案：

錯誤：「使用 CodeConnections 建立 CodeBuild 專案時，您的登入資料缺少一或多個必要的權限範圍」 CodeConnections

問題：使用 CodeConnections 建立 CodeBuild 專案時，您沒有安裝 Bitbucket Webhook 的許可。

可能原因：

建議解決方案：

錯誤：使用 Ubuntu 安裝命令建置時，「很抱歉，完全沒有終端請求 - 無法取得輸入」

問題：如果您正在執行 GPU 容器特殊權限組建，您可能會依照此程序安裝 NVIDIA Container Toolkit。在最新的 CodeBuild 映像版本中，CodeBuild 會在最新和精選的映像nvidia-container-toolkit中使用 ubuntu 預先安裝amazonlinux和設定 Docker。遵循此程序會導致使用 Ubuntu 安裝命令的組建失敗，並出現下列錯誤：

Running command curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | gpg --dearmor --no-tty -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
gpg: Sorry, no terminal at all requested - can't get input
curl: (23) Failed writing body

可能的原因：gpg 金鑰已存在於相同的位置。

建議的解決方案：nvidia-container-toolkit映像中已安裝 。如果您看到此錯誤，則可以略過 buildspec 中的安裝並重新啟動 docker 程序。

使用 Secrets Manager OAuth 後，Bitbucket 組建失敗並發生身分驗證錯誤

問題：使用 Bitbucket 做為來源提供者的建置失敗，並出現來源登入資料錯誤。Bitbucket 連線是使用 OAuth 搭配 AWS Secrets Manager 做為儲存服務來設定。

可能原因：Atlassian 會強制執行 Bitbucket OAuth 的一次性輪換重新整理權杖。每次使用重新整理權杖時，Bitbucket 都會將其失效並傳回新的權杖。如需詳細資訊，請參閱 Atlassian 開發人員網站上的 Bitbucket OAuth 單次使用重新整理權杖 (CHANGE-3052)。

建議的解決方案：將 secretsmanager:PutSecretValue 許可新增至 CodeBuild 服務角色。如需所需 IAM 許可的詳細資訊，請參閱 Secrets Manager 儲存的登入資料所需的動作。