故障排除 Amazon CodeBuild

使用本主题中的信息来帮助您识别、诊断和解决问题。要了解如何记录和监控 CodeBuild 版本以解决问题，请参阅日志记录和监控。

来自错误存储库的 Apache Maven 构建参考构件

问题：当你将 Maven 与 Amazon CodeBuild提供的 Java 构建环境一起使用时，Maven 会从安全的中央 Maven 存储库中提取构建和插件依赖项，网址为 https://repo1.maven.org/maven2。即使您构建项目的 pom.xml 文件明确声明会改用其他位置，也会发生这种情况。

可能的原因： CodeBuild提供的 Java 编译环境中包含一个名为的文件settings.xml，该文件已预先安装在构建环境的/root/.m2目录中。该 settings.xml 文件包含以下声明，这些声明将指示 Maven 始终从安全的 Maven 中央存储库（网址为 https://repo1.maven.org/maven2）中提取构建和插件依赖项。

<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 用户身份 Amazon CodeBuild 运行您的构建命令。即使您的相关构建映像的 Dockerfile 将 USER 指令设置为另一位用户，也会发生这种情况。

原因：默认情况下，以 root 用户身份 CodeBuild 运行所有构建命令。

建议的解决方案：无。

当文件名包含非美国英语字符时，构建可能失败

问题：当您运行的构建使用的文件的名称包含非美国英语字符（例如，中文字符）时，构建将失败。

可能的原因：提供的构建环境 Amazon CodeBuild 的默认区域设置为POSIX。 POSIX本地化设置 CodeBuild 与包含非美国文件名的兼容性较差 英文字符，并可能导致相关构建失败。

建议的解决方案：将以下命令添加到构建规范文件的 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 P EC2 arameter Store 获取参数时，构建可能会失败

问题：当版本尝试获取存储在 Amazon P EC2 arameter Store 中的一个或多个参数的值时，构建将在出现错误的DOWNLOAD_SOURCE阶段失败Parameter does not exist。

可能的原因：构建项目所依赖的服务角色无权调用ssm:GetParameters操作，或者构建项目使用由生成 Amazon CodeBuild 并允许调用ssm:GetParameters操作的服务角色，但参数的名称不是以开头的/CodeBuild/。

建议的解决方案：

无法在 CodeBuild 控制台中访问分支筛选条件

问题：创建或更新 Amazon CodeBuild 项目时，控制台中无法使用分支筛选器选项。

可能的原因：分支筛选选项已被弃用。它已被 Webhook 筛选条件组取代，后者可以更好地控制触发新 CodeBuild 中的构建的 Webhook 事件。

建议的解决方案：要迁移在引入 Webhook 筛选条件之前创建的分支筛选条件，请使用正则表达式 ^refs/heads/branchName$ 创建带 HEAD_REF 筛选条件的 Webhook 筛选条件组。例如，如果您的分支筛选条件正则表达式是 ^branchName$，那么您放入 HEAD_REF 筛选条件的经过更新的正则表达式是 ^refs/heads/branchName$。有关更多信息，请参阅Bitbucket Webhook 事件 和筛选 GitHub webhook 事件（控制台）。

无法查看构建是成功还是失败

问题：无法查看重试构建是成功还是失败。

可能的原因：未启用报告构建状态的选项。

推荐的解决方案：在创建或更新 CodeBuild 项目时启用 “报告构建状态”。此选项告知 CodeBuild 在触发构建时报告状态。有关更多信息，请参阅 Amazon CodeBuild API 参考中的 reportBuildStatus。

未向源提供商报告构建状态

问题：允许向源提供商（例如 GitHub 或 Bitbucket）报告构建状态后，构建状态未更新。

可能的原因：与源提供商关联的用户不具备访问存储库的权限。

建议的解决方案：为了能够向源提供商报告构建状态，与源提供商关联的用户必须拥有对存储库的写入权限。如果用户没有写入权限，则无法更新构建状态。有关更多信息，请参阅 源提供商访问权限。

无法找到并选择 Windows Server Core 2019 平台的基本映像

问题：无法找到或选择 Windows Server Core 2019 平台的基本映像。

可能的原因：您使用的 Amazon 区域不支持此图片。

建议的解决方案：使用以下支持 Windows Server Core 2019 平台基本映像的 Amazon 区域之一：

构建规范文件中的前期命令无法被后续命令识别

问题：buildspec 文件中的一个或多个命令的结果无法被同一 buildspec 文件中的后续命令识别。例如，某个命令可能会设置本地环境变量，但稍后运行的命令可能无法获取该本地环境变量的值。

可能的原因：在 buildspec 文件版本 0.1 中， Amazon CodeBuild 将在构建环境内的默认 Shell 的单独实例中运行每个命令。这表示各个命令独立于其他所有命令而运行。默认情况下，您无法运行依赖于任何先前命令的状态的单个命令。

建议的解决方案：建议您使用构建规范版本 0.2，它能解决此问题。如果您必须使用构建规范版本 0.1，建议您使用 Shell 命令链接运算符（例如，Linux 中的 &&）将多个命令合并为一个命令。或者，您也可以在源代码中包括一个带有多个命令的 Shell 脚本，然后从 buildspec 文件中的单个命令调用该 Shell 脚本。有关更多信息，请参阅构建环境中的 Shell 和命令 和构建环境中的环境变量。

尝试下载缓存时出现错误：“访问被拒绝”

问题：当尝试下载已启用缓存的构建项目上的缓存时，您收到 Access denied 错误。

可能的原因：

建议的解决方案：在首次使用时，在更新缓存配置后立即看到此错误是正常的。如果此错误持续存在，则您应该检查您的服务角色对包含缓存的 S3 存储桶是否具有 s3:GetObject 和 s3:PutObject 权限。有关更多信息，请参阅《Amazon S3 开发人员指南》中的指定 S3 权限。

使用自定义构建映像时出现错误“BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE”

问题：当您尝试运行使用自定义构建映像的构建时，构建将失败并返回错误 BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE。

错误：“构建容器在完成构建之前发现已失效。构建容器因内存不足而死亡，或者不支持 Docker 镜像。 ErrorCode: 500 英寸

问题：当你尝试在中使用微软 Windows 或 Linux 容器时 Amazon CodeBuild，此错误发生在配置阶段。

可能的原因：

建议的解决方案：

错误：运行构建时出现“无法连接到 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 镜像 Amazon CodeBuild，请参阅自定义镜像示例中的 Docker CodeBuild。

创建或更新构建项目时出现错误：AssumeRole“无权执行：st CodeBuild s:”

问题：当您尝试创建或更新构建项目时，您会收到错误 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 输出存储桶（ Amazon CodeBuild 存储其生成输出的存储桶）位于与 CodeBuild 构建项目不同的 Amazon 区域。

推荐的解决方案：更新构建项目的设置，使其指向与构建项目位于同一 Amazon 区域的输出存储桶。

错误：“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 存储桶中，而该存储桶位于与 Amazon CodeBuild 构建项目不同的 Amazon 区域。

建议的解决方案：更新构建项目的设置，以指向包含预构建的源代码的存储桶。确保该存储桶与构建项目位于同一个 Amazon 区域。

错误：“此构建映像需要至少选择一个运行时版本。”

问题：在运行构建时，DOWNLOAD_SOURCE 构建阶段失败并出现错误 YAML_FILE_ERROR: This build image requires selecting at least one runtime version。

可能的原因：您的版本使用了 Amazon Linux 2 (AL2) 标准映像的 1.0 或更高版本，或 Ubuntu 标准映像的 2.0 或更高版本，并且在构建规范文件中未指定运行时间。

推荐的解决方案：如果您使用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 地址无法供您使用，而且无法分配到一个实例。例如，在具有 CIDR 块 10.0.0.0/24 的子网中，以下五个 IP 地址是保留的：

建议的解决方案：检查您的 VPC 是否使用了预留 IP 地址。将任何预留的 IP 地址替换为未预留的 IP 地址。有关更多信息，请参阅《Amazon VPC 用户指南》中的 VPC 和子网大小调整。

错误：“无法下载缓存： RequestError：发送请求失败原因是：x509：无法加载系统根目录且未提供根目录”

问题： 当您尝试运行构建项目时，构建失败并出现此错误。

可能的原因：您将缓存配置为您的构建项目的一部分并使用包含过期根证书的较旧 Docker 映像。

推荐的解决方案：更新项目中正在使用的 Docker 镜像。 Amazon CodeBuild 有关更多信息，请参阅 提供的 Docker 镜像 CodeBuild。

错误：“无法从 S3 下载证书。 AccessDenied”

问题： 当您尝试运行构建项目时，构建失败并出现此错误。

可能的原因：

建议的解决方案：

错误：“找不到凭证”

问题：当你尝试运行 Amazon CLI、使用 Amazon SDK 或调用其他类似组件作为构建的一部分时，你会遇到与 Amazon CLI、 Amazon SDK 或组件直接相关的构建错误。例如，您可能会收到构建错误，如 Unable to locate credentials。

可能的原因：

建议的解决方案：

RequestError CodeBuild 在代理服务器上运行时出现超时错误

问题：您收到类似于以下内容的 RequestError 错误：

可能的原因：

建议的解决方案：

bourne shell（sh）必须存在于构建映像中

问题：您使用的构建映像不是由提供的 Amazon CodeBuild，并且您的构建失败并显示消息Build container found dead before completing the build。

可能的原因：Bourne 外壳 (sh) 未包含在您的构建镜像中。 CodeBuild sh需要运行构建命令和脚本。

推荐的解决方案：如果您的构建映像sh中没有，请务必在开始使用您的映像的更多构建之前将其包含在内。 （CodeBuild 已包含sh在其构建镜像中。）

警告：“跳过运行时安装。此构建映像不支持运行时版本选择”（在运行构建时出现）

问题：在运行构建时，构建日志包含此警告。

可能的原因：您的版本未使用版本 1.0 或更高版本的 Amazon Linux 2 (AL2) 标准映像，也未使用 Ubuntu 标准映像的 2.0 或更高版本，并且在构建规范文件的某个runtime-versions部分中指定了运行时间。

建议的解决方案：确保 buildspec 文件不包含 runtime-versions 部分。只有当您使用 Amazon Linux 2 (AL2) 标准映像或更高版本或 Ubuntu 标准映像版本 2.0 或更高版本时，才需要此runtime-versions部分。

错误：打开 CodeBuild 控制台时出现 “无法验证 JobWorker 身份”

问题：打开 CodeBuild 控制台时，会显示 “无法验证 JobWorker 身份” 错误消息。

可能的原因：用于控制台访问的 IAM 角色的标签以 jobId 作为键。此标签密钥是为之保留的 CodeBuild ，如果存在则会导致此错误。

建议的解决方案：将任何具有 jobId 键的自定义 IAM 角色标签更改为具有其他键，例如 jobIdentifier。

构建启动失败

问题：启动构建时，您会收到构建启动失败错误消息。

可能的原因：已达到并发构建的数量。

建议的解决方案：等到其他构建完成，或者增加项目的并发构建限制，然后重新启动构建。有关更多信息，请参阅 项目配置。

访问本地缓存版本中的 GitHub 元数据

问题：在某些情况下，缓存构建中的 .git 目录是文本文件，而不是目录。

可能的原因：为版本启用本地源代码缓存后， CodeBuild 会为该.git目录创建一个 gitlink。这意味着该 .git 目录实际上是一个包含目录路径的文本文件。

建议的解决方案：在所有情况下，都使用以下命令获取 Git 元数据目录。无论 .git 采用何种格式，此命令都将起作用：

git rev-parse --git-dir

AccessDenied：报告组的存储桶所有者与 S3 存储桶的所有者不匹配...

问题：将测试数据上传到 Amazon S3 存储桶 CodeBuild 时，无法将测试数据写入存储桶。

可能的原因：

建议的解决方案：

使用以下命令创建 CodeBuild 项目时出现错误：“您的凭证缺少一个或多个必需的权限范围” CodeConnections

问题：使用创建 CodeBuild 项目时 CodeConnections，您无权安装 Bitbucket webhook。

可能的原因：

建议的解决方案：

错误：使用 Ubuntu 安装命令构建时出现 “对不起，根本没有请求终端——无法获取输入”

问题：如果您正在运行 GPU 容器特权版本，则可能要按照以下步骤安装 NVIDIA 容器工具包。在最新版本的 CodeBuild 镜像中，使用最新的amazonlinux精选镜像 CodeBuild 预安装和配置 d nvidia-container-toolkit ocker。ubuntu按照此步骤操作将导致使用 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 进程。