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

# 快取建置以改善效能
<a name="build-caching"></a>

當您的專案使用快取來建置時，可以為您省下時間。快取可以存放組建環境的可重複使用部分，並在多個組建間使用這些部分。您的建置專案可以使用兩種快取類型的其中之一：Amazon S3 或本機。如果您使用本機快取，您必須從三種快取模式中選擇一或多種：來源快取、Docker 層快取和自訂快取。

**注意**  
Docker 層快取模式僅適用於 Linux 環境。如果您選擇此模式，您必須以特殊權限模式執行您的組建。CodeBuild 專案授予特權模式會授予其容器存取所有裝置的權限。如需詳細資訊，請參閱 Docker Docs 網站上的[執行期權限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)。

**Topics**
+ [Amazon S3 快取](caching-s3.md)
+ [本機快取](caching-local.md)
+ [指定本機快取](specify-caching-local.md)

# Amazon S3 快取
<a name="caching-s3"></a>

Amazon S3 快取會將快取存放在跨多個建置主機可用的 Amazon S3 儲存貯體中。對於較下載更昂貴的中小型建置成品，這是理想的選項。

若要在建置中使用 Amazon S3，您可以指定要在 中快取之檔案的路徑`buildspec.yml`。CodeBuild 會自動將快取儲存並更新至專案上設定的 Amazon S3 位置。如果您未指定檔案路徑，CodeBuild 會盡最大努力快取常見的語言相依性，以協助您加速建置。您可以在建置日誌中檢視快取詳細資訊。

此外，如果您想要有多個版本的快取，您可以在 中定義快取金鑰`buildspec.yml`。CodeBuild 會將快取存放在此快取金鑰的內容下，並建立唯一的快取複本，一旦建立就不會更新。快取金鑰也可以跨專案共用。只有在指定金鑰時，才能使用動態金鑰、快取版本控制和跨組建快取共用等功能。

若要進一步了解 buildspec 檔案中的快取語法，請參閱 buildspec 參考[快取](build-spec-ref.md#build-spec.cache)中的 。

**Topics**
+ [產生動態金鑰](#caching-s3-dynamic)
+ [codebuild-hash-files](#caching-s3-dynamic.codebuild-hash-files)
+ [快取版本](#caching-s3-version)
+ [專案之間的快取共用](#caching-s3-sharing)
+ [Buildspec 範例](#caching-s3-examples)

## 產生動態金鑰
<a name="caching-s3-dynamic"></a>

快取金鑰可以包含 Shell 命令和環境變數，使其獨一無二，並在金鑰變更時啟用自動快取更新。例如，您可以使用 `package-lock.json` 檔案的雜湊來定義金鑰。當該檔案中的相依性變更時，雜湊 - 因此是快取金鑰 - 會變更，觸發自動建立新的快取。

```
cache:
    key: npm-key-$(codebuild-hash-files package-lock.json)
```

CodeBuild 將評估表達式`$(codebuild-hash-files package-lock.json)`以取得最終索引鍵：

```
npm-key-abc123
```

您也可以使用環境變數定義快取金鑰，例如 `CODEBUILD_RESOLVED_SOURCE_VERSION`。這可確保每當來源變更時，都會產生新的金鑰，進而自動儲存新的快取：

```
cache:
   key: npm-key-$CODEBUILD_RESOLVED_SOURCE_VERSION
```

CodeBuild 將評估表達式並取得最終索引鍵：

```
npm-key-046e8b67481d53bdc86c3f6affdd5d1afae6d369
```

## codebuild-hash-files
<a name="caching-s3-dynamic.codebuild-hash-files"></a>

`codebuild-hash-files` 是一種 CLI 工具，可使用 glob 模式計算 CodeBuild 來源目錄中一組檔案的 SHA-256 雜湊：

```
codebuild-hash-files <glob-pattern-1> <glob-pattern-2> ...
```

以下是使用 的一些範例`codebuild-hash-files`：

```
codebuild-hash-files package-lock.json
codebuild-hash-files '**/*.md'
```

## 快取版本
<a name="caching-s3-version"></a>

快取版本是從要快取之目錄的路徑產生的雜湊。如果兩個快取有不同的版本，則在比對程序期間會將它們視為不同的快取。例如，以下兩個快取會被視為不同，因為它們參考不同的路徑：

```
version: 0.2

phases:
  build:
    commands:
      - pip install pandas==2.2.3 --target pip-dependencies
cache:
  key: pip-dependencies 
  paths:
    - "pip-dependencies/**/*"
```

```
version: 0.2

phases:
  build:
    commands:
      - pip install pandas==2.2.3 --target tmp/pip-dependencies
cache:
  key: pip-dependencies 
  paths:
    - "tmp/pip-dependencies/**/*"
```

## 專案之間的快取共用
<a name="caching-s3-sharing"></a>

您可以使用 `cache`區段下的 `cacheNamespace` API 欄位，跨多個專案共用快取。此欄位定義快取的範圍。若要共用快取， 必須執行下列動作：
+ 使用相同的 `cacheNamespace`。
+ 指定相同的快取 `key`。
+ 定義相同的快取路徑。
+ `pathPrefix` 如果設定，請使用相同的 Amazon S3 儲存貯體和 。

這可確保一致性，並啟用跨專案的快取共用。

### 指定快取命名空間 （主控台）
<a name="caching-s3-sharing.console"></a>

1. 在 https：//[https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home) 開啟 AWS CodeBuild 主控台。

1. 選擇**建立專案**。如需詳細資訊，請參閱 [建立組建專案 (主控台)](create-project.md#create-project-console) 及 [執行建置 (主控台)](run-build-console.md)。

1. 在**成品**中，選擇**其他組態**。

1. 針對**快取類型**，選擇 **Amazon S3**。

1. 針對**快取命名空間 - 選用**，輸入命名空間值。  
![\[CodeBuild 主控台中的快取命名空間參數。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/s3-cache-namespace.png)

1. 繼續執行預設值，然後選擇**建立建置專案**。

### 指定快取命名空間 (AWS CLI)
<a name="caching-s3-sharing.cli"></a>

您可以使用 中的 `--cache` 參數 AWS CLI 來指定快取命名空間。

```
--cache '{"type": "S3", "location": "your-s3-bucket", "cacheNamespace": "test-cache-namespace"}'
```

## Buildspec 範例
<a name="caching-s3-examples"></a>

以下是幾個常見語言的 buildspec 範例：

**Topics**
+ [快取 Node.js 相依性](#caching-s3-examples.nodejs)
+ [快取 Python 相依性](#caching-s3-examples.python)
+ [快取 Ruby 相依性](#caching-s3-examples.ruby)
+ [快取 Go 相依性](#caching-s3-examples.go)

### 快取 Node.js 相依性
<a name="caching-s3-examples.nodejs"></a>

如果您的專案包含 `package-lock.json` 檔案並使用 `npm` 來管理 Node.js 相依性，下列範例會示範如何設定快取。根據預設， 會將相依性`npm`安裝到 `node_modules`目錄中。

```
version: 0.2

phases:
  build:
    commands:
      - npm install
cache:
  key: npm-$(codebuild-hash-files package-lock.json)
  paths:
    - "node_modules/**/*"
```

### 快取 Python 相依性
<a name="caching-s3-examples.python"></a>

如果您的專案包含 `requirements.txt` 檔案並使用 pip 來管理 Python 相依性，下列範例會示範如何設定快取。根據預設，pip 會將套件安裝到系統的`site-packages`目錄中。

```
version: 0.2

phases:
  build:
    commands:
      - pip install -r requirements.txt
cache:
  key: python-$(codebuild-hash-files requirements.txt)
  paths:
    - "/root/.pyenv/versions/${python_version}/lib/python${python_major_version}/site-packages/**/*"
```

此外，您可以在特定目錄中安裝相依性，並設定該目錄的快取。

```
version: 0.2

phases:
  build:
    commands:
      - pip install -r requirements.txt --target python-dependencies
cache:
  key: python-$(codebuild-hash-files requirements.txt)
  paths:
    - "python-dependencies/**/*"
```

### 快取 Ruby 相依性
<a name="caching-s3-examples.ruby"></a>

如果您的專案包含 `Gemfile.lock` 檔案並使用 `Bundler` 來管理 Gem 相依性，下列範例會示範如何有效設定快取。

```
version: 0.2

phases:
  build:
    commands:
      - bundle install --path vendor/bundle
cache:
  key: ruby-$(codebuild-hash-files Gemfile.lock)
  paths:
    - "vendor/bundle/**/*"
```

### 快取 Go 相依性
<a name="caching-s3-examples.go"></a>

如果您的專案包含 `go.sum` 檔案，並使用 Go 模組來管理相依性，下列範例會示範如何設定快取。根據預設，Go 模組會下載並存放在 `${GOPATH}/pkg/mod`目錄中。

```
version: 0.2

phases:
  build:
    commands:
      - go mod download
cache:
  key: go-$(codebuild-hash-files go.sum)
  paths:
    - "/go/pkg/mod/**/*"
```

# 本機快取
<a name="caching-local"></a>

本機快取將快取存放在組建主機的本機，而僅供該組建主機使用。這是中大型建置成品的好選項，因為快取可立即在建置主機上使用。如果是不常存取的組建，這不是最佳選項。這表示組建效能不會受到網路傳輸時間所影響。

如果您選擇本機快取，您必須選擇以下一或多個快取模式：
+ 來源快取模式會快取主要和次要來源的 Git 中繼資料。建立快取之後，後續組建只會提取遞交之間的變更。如果專案有全新的工作目錄，且來源是大型的 Git 儲存庫，此模式是很好的選擇。如果您選擇此選項，且您的專案不使用 Git 儲存庫 (AWS CodeCommit、GitHub、GitHub Enterprise Server 或 Bitbucket)，則會忽略此選項。
+ Docker 層快取模式會快取現有的 Docker 層。如果專案會建置或提取大型 Docker 影像，此模式是很好的選擇。它可以避免從網路提取大型 Docker 影像所造成的效能問題。
**注意**  
您只能在 Linux 環境中使用 Docker 層快取。
您必須設定 `privileged` 旗標，專案才能具備所需的 Docker 許可。  
預設會為非 VPC 建置啟用 Docker 協助程式。如果您想要將 Docker 容器用於 VPC 建置，請參閱 Docker 文件網站上的[執行期權限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)，並啟用特權模式。此外，Windows 不支援特殊權限模式。
使用 Docker 層快取之前，您應該考慮安全隱憂。
+ 自訂快取模式會快取您在 buildspec 檔案中指定的目錄。如果您的組建案例不適合其他兩個本機快取模式，此模式是很好的選擇。如果您使用自訂快取：
  + 只能指定目錄來快取。您不能指定個別檔案。
  + 符號連結用來參考快取的目錄。
  + 在您的組建下載其專案來源之前，快取的目錄會連結到您的組建。如果快取項目具有相同名稱，則會覆寫來源項目。目錄的指定方式是使用 buildspec 檔案中的快取路徑。如需詳細資訊，請參閱[Buildspec 語法](build-spec-ref.md#build-spec-ref-syntax)。
  + 避免來源和快取中的目錄名稱相同。本機快取的目錄可能會覆寫或刪除具有相同名稱之來源儲存庫中的目錄內容。

**注意**  
`LINUX_GPU_CONTAINER` 環境類型和`BUILD_GENERAL1_2XLARGE`運算類型不支援本機快取。如需詳細資訊，請參閱[建置環境運算模式和類型](build-env-ref-compute-types.md)。

**注意**  
當您設定 CodeBuild 使用 VPC 時，不支援本機快取。如需搭配 CodeBuild 使用 VPCs 的詳細資訊，請參閱 [AWS CodeBuild 搭配 Amazon Virtual Private Cloud 使用](vpc-support.md)。

# 指定本機快取
<a name="specify-caching-local"></a>

您可以使用 AWS CLI、 主控台、 SDK 或 CloudFormation 來指定本機快取。如需本機快取的詳細資訊，請參閱 [本機快取](caching-local.md)。

**Topics**
+ [指定本機快取 (CLI)](#caching-local-cli)
+ [指定本機快取 (主控台)](#caching-local-console)
+ [指定本機快取 (CloudFormation)](#caching-local-cfn)

## 指定本機快取 (CLI)
<a name="caching-local-cli"></a>

您可以使用 中的 `--cache` 參數 AWS CLI 來指定三種本機快取類型的每一個。
+ 若要指定來源快取：

  ```
  --cache type=LOCAL,mode=[LOCAL_SOURCE_CACHE]
  ```
+ 若要指定 Docker 層快取：

  ```
  --cache type=LOCAL,mode=[LOCAL_DOCKER_LAYER_CACHE]
  ```
+ 若要指定自訂快取：

  ```
  --cache type=LOCAL,mode=[LOCAL_CUSTOM_CACHE]
  ```

如需詳細資訊，請參閱[建立建置專案 (AWS CLI)](create-project.md#create-project-cli)。

## 指定本機快取 (主控台)
<a name="caching-local-console"></a>

您可以在主控台的 **Artifacts (成品)** 區段中指定快取。針對**快取類型**，選擇 **Amazon S3** 或 **Local**。如果您選擇 **Local (本機)**，請從三種本機快取選項中選擇一或多種。

![\[透過選擇三個本機快取選項中的一個或多個來指定本機快取。\]](http://docs.aws.amazon.com/zh_tw/codebuild/latest/userguide/images/local-cache.png)


如需詳細資訊，請參閱[建立組建專案 (主控台)](create-project.md#create-project-console)。

## 指定本機快取 (CloudFormation)
<a name="caching-local-cfn"></a>

如果您使用 CloudFormation 指定本機快取，請在 `Cache` 屬性上指定 `Type``LOCAL`。下列 YAML 格式 CloudFormation 程式碼範例會指定所有三種本機快取類型。您可以指定這些類型的任意組合。如果您使用 Docker 層快取，在 `Environment` 下，您必須將 `PrivilegedMode` 設定為 `true`，將 `Type` 設定為 `LINUX_CONTAINER`。

```
CodeBuildProject:
    Type: AWS::CodeBuild::Project
    Properties:
      Name: MyProject
      ServiceRole: <service-role>
      Artifacts:
        Type: S3
        Location: <bucket-name>
        Name: myArtifact
        EncryptionDisabled: true
        OverrideArtifactName: true
      Environment:
        Type: LINUX_CONTAINER
        ComputeType: BUILD_GENERAL1_SMALL
        Image: aws/codebuild/standard:5.0
        Certificate: <bucket/cert.zip>
        # PrivilegedMode must be true if you specify LOCAL_DOCKER_LAYER_CACHE
        PrivilegedMode: true
      Source:
        Type: GITHUB
        Location: <github-location>
        InsecureSsl: true
        GitCloneDepth: 1
        ReportBuildStatus: false
      TimeoutInMinutes: 10
      Cache:
        Type: LOCAL
        Modes: # You can specify one or more cache mode, 
          - LOCAL_CUSTOM_CACHE
          - LOCAL_DOCKER_LAYER_CACHE
          - LOCAL_SOURCE_CACHE
```

**注意**  
預設會為非 VPC 建置啟用 Docker 協助程式。如果您想要將 Docker 容器用於 VPC 建置，請參閱 Docker 文件網站上的[執行期權限和 Linux 功能](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)，並啟用特權模式。此外，Windows 不支援特殊權限模式。

如需詳細資訊，請參閱[建立建置專案 (CloudFormation)](create-project.md#create-project-cloud-formation)。