AWS CodeBuild

用户指南 (API 版本 2016-10-06)

AWS 文档 » AWS CodeBuild » 用户指南 » CodeBuild 问题排查

CodeBuild 问题排查

使用本主题中的信息来帮助您识别、诊断和解决问题。

创建或更新构建项目时收到错误：“CodeBuild 无权执行：sts:AssumeRole”

问题：在尝试创建或更新构建项目时，您收到以下错误：“代码：InvalidInputException，消息：CodeBuild 无权在 arn:aws:iam::account-ID:role/service-role-name 上执行：sts:AssumeRole”。

可能的原因：

建议的解决方案：

错误：“This build image requires selecting at least one runtime version. (此构建映像需要至少选择一个运行时版本。)”

问题：当您运行构建时，DOWNLOAD_SOURCE 构建阶段会失败，并出现错误“YAML_FILE_ERROR: This build image requires selecting at least one runtime version. (YAML_FILE_ERROR：此构建映像需要至少选择一个运行时版本。)”

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

建议的解决方案：如果您使用 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

有关更多信息，请参阅 在 Buildspec 文件中指定运行时版本。

错误：运行生成包时出现“Cannot connect to the Docker daemon (无法连接到 Docker 守护程序)”

问题：您的生成包失败，并在生成包日志中收到了类似于 Cannot connect to the Docker daemon at unix:/var/run/docker.sock. Is the docker daemon running? 的错误。

可能的原因：您未在特权模式下运行生成包。

建议的解决方案：在特权模式下运行生成包：

1. Open the CodeBuild console at https://console.amazonaws.cn/codebuild/.

2. 在导航窗格中选择 Build projects (构建项目)，然后选择您的生成包。

3. 从 Edit (编辑) 中，选择 Environment (环境)。

4. 选择 Override images (覆盖映像)，然后选择 Environment (环境)。

5. 指定环境映像、操作系统、运行时和映像。这些应与您失败的生成包的设置匹配。

6. 选择 Privileged (特权)。

7. 选择 Update environment (更新环境)。

8. 选择 Start build (启动构建) 来重试您的生成包。

警告：“Skipping install of runtimes.Runtime version selection is not supported by this build image (跳过运行时安装。此构建映像不支持运行时版本选择)”（在运行构建时出现）

问题：在运行构建时，构建日志包含以下警告：““Skipping install of runtimes.Runtime version selection is not supported by this build image (跳过运行时安装。此构建映像不支持运行时版本选择)””

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

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

运行构建时收到错误：“必须使用指定的终端节点来寻址当前尝试访问的存储桶”

问题：在运行构建时，DOWNLOAD_SOURCE 构建阶段失败并显示以下错误：“必须使用指定的终端节点来寻址当前尝试访问的存储桶。请将未来的所有请求发送到此终端节点”。

可能的原因：您预先构建的源代码存储在 Amazon S3 存储桶中，而该存储桶与 AWS CodeBuild 构建项目位于不同的 AWS 区域。

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

错误：“error calling GetBucketAcl: either the bucket owner has changed or the service role no longer has permission to called s3:GetBucketAcl (调用 GetBucketAcl 时出错：存储桶拥有者已更改，或者服务角色不再拥有调用 S3:GetBucketAcl 的权限)”

问题：运行生成包时，您收到一个有关 Amazon S3 存储桶所有权更改和 GetBucketAcl 权限更改的错误。

可能的原因：您将 s3:GetBucketACL 和 s3:GetBucketLocation 权限添加到了 IAM 角色。这些权限可保护您项目的 Amazon S3 存储桶，并确保只有您可以访问它。添加完这些权限之后，Amazon S3 存储桶的拥有者会发生更改。

建议的解决方案：验证您是 Amazon S3 存储桶的拥有者，然后重新将权限添加到您的 IAM 角色。有关更多信息，请参阅 安全访问 Amazon S3 存储桶。

运行构建时收到错误：“无法上传项目：arn 无效”

问题：在运行构建时，UPLOAD_ARTIFACTS 构建阶段失败并显示以下错误：“无法上传项目：arn 无效”。

可能的原因：您的Amazon S3 输出存储桶（AWS CodeBuild 用于存储其构建输出的存储桶）与 CodeBuild 构建项目位于不同的 AWS 区域。

建议的解决方案：更新构建项目的设置，以指向与该构建项目位于同一区域的输出存储桶。

错误：“Unable to Locate Credentials”

问题：在尝试运行 AWS CLI、使用 AWS 开发工具包或调用其他类似组件作为构建的一部分时，您收到与 AWS CLI、AWS 开发工具包或组件直接相关的构建错误。例如，您可能会收到以下构建错误：“无法查找凭证”。

可能的原因：

建议的解决方案：

Buildspec 文件中的前期命令无法被后续命令识别

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

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

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

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

问题：在将 Maven 与 AWS 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>

建议的解决方案：执行以下操作：

1. 向源代码中添加 settings.xml 文件。

2. 在此 settings.xml 文件中，使用上述 settings.xml 格式作为指导，声明您希望 Maven 从哪些存储库中提取构建和插件依赖项。

3. 在构建项目的 install 阶段，指示 CodeBuild 将您的 settings.xml 文件复制到构建环境的 /root/.m2 目录。例如，考虑说明此行为的 buildspec.yml 文件中的以下代码段。

   version 0.2
   
   phases:
     install:
       commands:
         - cp ./settings.xml /root/.m2/settings.xml

默认情况下，构建命令以根用户身份运行

问题：AWS CodeBuild 以根用户身份运行您的构建命令。即使您的相关构建映像的 Dockerfile 将 USER 指令设置为另一位用户，也会发生这种情况。

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

建议的解决方案：无。

Bourne 外壳 (sh) 必须存在于构建映像中

问题：您使用的不是 AWS CodeBuild 提供的构建映像，并且您的构建失败并返回消息“build container found dead before completing the build (构建容器在完成构建前发现了死信)”。

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

建议的解决方案：如果您的构建映像中不存在 sh，请确保您在启动使用映像的任何其他构建前包含该构建。（CodeBuild 已将 sh 包含在其构建映像中）

运行构建时出现错误“CodeBuild is experiencing an issue (AWS CodeBuild 遇到了一个问题)”

问题：当您尝试运行构建项目时，您将在构建的 PROVISIONING 阶段收到以下错误消息：“CodeBuild is experiencing an issue (AWS CodeBuild 遇到了一个问题)”。

可能的原因：您的构建所使用的环境变量对 AWS CodeBuild 来说过大。当所有环境变量的长度（所有名称和值相加）超出最大组合长度（约 5,500 个字符）时，CodeBuild 可能引发错误。

建议的解决方案：使用 Amazon EC2 Systems Manager Parameter Store 存储大型环境变量，然后从您的 buildspec 文件中检索它们。Amazon EC2 Systems Manager Parameter Store 可以存储组合长度为 4,096 个字符或更少的字符的独立环境变量 (名称和值加在一起)。要存储大型环境变量，请参阅 Amazon EC2 Systems Manager 用户指南 中的 Systems Manager Parameter Store 和 Systems Manager Parameter Store 控制台演练。要检索它们，请参阅生成规范语法中的 parameter-store 映射。

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

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

可能的原因：

建议的解决方案：

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

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

可能的原因：由 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 locales

对于基于 Amazon Linux 的构建环境：

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

当从 Amazon EC2 Parameter Store 获取参数时，构建可能失败

问题：当构建尝试获取存储在 Amazon EC2 Parameter Store 中的一个或多个参数的值时，处于 DOWNLOAD_SOURCE 阶段的构建将失败并返回以下错误：“Parameter does not exist (参数不存在)”。

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

建议的解决方案：

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

问题：创建或更新 AWS CodeBuild 项目时，控制台中的分支筛选选项不可用。

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

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

本指南中的步骤与 CodeBuild 控制台不匹配

问题：本指南中的过程支持新的控制台设计。

可能的原因：您正在使用旧控制台设计。本指南支持新控制台设计。如果您选择使用较旧版本的控制台，可以在本指南中找到许多仍然适用的概念和基本过程。要访问新控制台中的帮助，请选择信息图标。

建议的解决方案：使用最新的控制台设计。

尝试下载缓存时出现“Access denied (拒绝访问)”错误消息

问题：当尝试下载已启用缓存的构建项目上的缓存时，您收到以下一般性错误消息：“Access denied (拒绝访问)”。

可能的原因：

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

错误：“Unable to download cache: RequestError: send request failed caused by: x509: failed to load system roots and no roots provided”(无法下载缓存: 请求错误: 发送请求失败原因: x509: 无法加载系统根，没有提供任何根)

问题：当您尝试运行构建项目时，构建失败，错误消息为：“RequestError: send request failed caused by: x509: failed to load system roots and no roots provided”(请求错误: 发送请求失败原因: x509: 无法加载系统根，没有提供任何根)。

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

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

错误："Unable to download certificate from S3.AccessDenied"

问题：当您尝试运行构建项目时，构建失败，错误消息为 "Unable to download certificate from S3.AccessDenied".

可能的原因：

建议的解决方案：

错误："Git Clone Failed: unable to access 'your-repository-URL': SSL certificate problem: self signed certificate"

问题：当您尝试运行构建项目时，构建失败，错误消息为“Git Clone Failed: unable to access 'your-repository-URL': SSL certificate problem: self signed certificate”(Git 克隆失败: 无法访问 'your-repository-URL': SSL 证书问题: 自签名证书)。

可能的原因：您的源存储库具有一个自签名证书，但您在构建项目的过程中未选择从您的 S3 存储桶安装此证书。

建议的解决方案：

错误：“The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation”(策略的默认版本不是通过增强的零单击角色创建来创建的或不是通过增强的零单击角色创建来创建的最新版本)。

问题：当您尝试在控制台中更新项目时，更新失败，错误消息为：“The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation”(策略的默认版本不是通过增强的零单击角色创建来创建的或不是通过增强的零单击角色创建来创建的最新版本)。

可能的原因：

建议的解决方案：

Error: "Build container found dead before completing the build.Build container died because it was out of memory, or the Docker image is not supported.ErrorCode: 500" (错误:“在完成构建之前，发现构建容器已不活动。构建容器因内存不够或不支持 Docker 镜像而不活动。错误代码: 500”)

问题：当您尝试在 AWS CodeBuild 中使用 Microsoft Windows 或 Linux 容器时，预置阶段出现错误。

可能的原因：

建议的解决方案：

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

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

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

建议的解决方案：在创建或更新 CodeBuild 项目时启用 Report build status (报告构建状态)。此选项告知 CodeBuild 在触发构建时报告状态。有关更多信息，请参阅 reportBuildStatus。

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

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

可能的原因：您使用的区域不支持此映像。

建议的解决方案：使用支持 Windows Server Core 2016 平台基本映像的其中一个区域：

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

问题：您从 CloudWatch Logs 收到类似于 RequestError: send request failed caused by: Post https://logs.<your-region>.amazonaws.com/: dial tcp 52.46.158.105:443: i/o timeout 的错误。

可能的原因：

建议的解决方案：

构建队列中的构建失败时出现错误“QUEUED: INSUFFICIENT_SUBNET”

问题：构建队列中的构建失败，出现类似于 QUEUED: INSUFFICIENT_SUBNET 的错误。

可能的原因：为 VPC 指定的 IPv4 CIDR 块使用了预留 IP 地址。每个子网 CIDR 块中的前四个 IP 地址和最后一个 IP 地址无法供您使用，而且无法分配到一个实例。例如，在具有 CIDR 块 10.0.0.0/24 的子网中，以下五个 IP 地址是保留的：

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

本页内容：

• 创建或更新构建项目时收到错误：“CodeBuild 无权执行：sts:AssumeRole”
• 错误：“This build image requires selecting at least one runtime version. (此构建映像需要至少选择一个运行时版本。)”
• 错误：运行生成包时出现“Cannot connect to the Docker daemon (无法连接到 Docker 守护程序)”
• 警告：“Skipping install of runtimes.Runtime version selection is not supported by this build image (跳过运行时安装。此构建映像不支持运行时版本选择)”（在运行构建时出现）
• 运行构建时收到错误：“必须使用指定的终端节点来寻址当前尝试访问的存储桶”
• 错误：“error calling GetBucketAcl: either the bucket owner has changed or the service role no longer has permission to called s3:GetBucketAcl (调用 GetBucketAcl 时出错：存储桶拥有者已更改，或者服务角色不再拥有调用 S3:GetBucketAcl 的权限)”
• 运行构建时收到错误：“无法上传项目：arn 无效”
• 错误：“Unable to Locate Credentials”
• Buildspec 文件中的前期命令无法被后续命令识别
• 来自错误存储库的 Apache Maven 构建参考项目
• 默认情况下，构建命令以根用户身份运行
• Bourne 外壳 (sh) 必须存在于构建映像中
• 运行构建时出现错误“CodeBuild is experiencing an issue (AWS CodeBuild 遇到了一个问题)”
• 使用自定义构建映像时出现错误“BUILD_CONTAINER_UNABLE_TO_PULL_IMAGE”
• 当文件名包含非美国英语字符时构建可能会失败
• 当从 Amazon EC2 Parameter Store 获取参数时，构建可能失败
• 无法在 CodeBuild 控制台中访问分支筛选条件
• 本指南中的步骤与 CodeBuild 控制台不匹配
• 尝试下载缓存时出现“Access denied (拒绝访问)”错误消息
• 错误：“Unable to download cache: RequestError: send request failed caused by: x509: failed to load system roots and no roots provided”(无法下载缓存: 请求错误: 发送请求失败原因: x509: 无法加载系统根，没有提供任何根)
• 错误："Unable to download certificate from S3.AccessDenied"
• 错误："Git Clone Failed: unable to access 'your-repository-URL': SSL certificate problem: self signed certificate"
• 错误：“The policy's default version was not created by enhanced zero click role creation or was not the most recent version created by enhanced zero click role creation”(策略的默认版本不是通过增强的零单击角色创建来创建的或不是通过增强的零单击角色创建来创建的最新版本)。
• Error: "Build container found dead before completing the build.Build container died because it was out of memory, or the Docker image is not supported.ErrorCode: 500" (错误:“在完成构建之前，发现构建容器已不活动。构建容器因内存不够或不支持 Docker 镜像而不活动。错误代码: 500”)
• 无法查看构建是成功还是失败
• 无法找到并选择 Windows Server Core 2016 平台的基本映像
• 在代理服务器中运行 CodeBuild 时出现 RequestError 超时错误
• 构建队列中的构建失败时出现错误“QUEUED: INSUFFICIENT_SUBNET”