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

# 安裝 Finch以搭配 CLI AWS SAM 使用
<a name="install-finch"></a>

Finch 是 AWS的容器開發工具，提供 的替代方案Docker，特別有益於 macOS 和 Linux 系統。如需詳細資訊，請參閱 [ GitHub 上的 Finch](https://github.com/runfinch)。透過 Finch， AWS SAM 可以提供類似於 AWS Lambda 容器的本機環境，以建置、測試和偵錯無伺服器應用程式。

**注意**  
您需要Finch在本機測試應用程式、使用 `--use-container`選項建置部署套件，以及建置 OCI 映像函數。從 AWS SAM CLI 1.145.0 版開始， AWS SAM CLI 支援 Finch做為 的替代容器執行時間Docker。

**Topics**
+ [安裝 Finch](#install-finch-instructions)
+ [Finch 使用 CLI AWS SAM 設定](#install-finch-configuration)
+ [驗證安裝](#install-finch-verification)
+ [停用 Finch](#install-finch-stopping)
+ [疑難排解](#install-finch-troubleshooting)
+ [後續步驟](#install-finch-next-steps)

## 安裝 Finch
<a name="install-finch-instructions"></a>

請依照這些指示，在您的作業系統Finch上安裝 。

### 先決條件
<a name="install-finch-prerequisites"></a>

**注意**  
Finch CLI AWS SAM 中的 整合可在 macOS 和 Linux 系統上使用。對於 Windows 使用者，請考慮使用虛擬機器或 Linux 環境來提供Finch功能。

**macOS 版本：**
+ macOS 15 Sequoia
+ macOS 14 Sonoma

**注意**  
Finch 支援最新的兩個版本的 macOS。

**Linux**︰
+ Linux 核心 v4.x\+

### 安裝 Finch
<a name="install-finch"></a>

#### macOS
<a name="install-finch-instructions-macos"></a>

**在 macOS 上安裝 Finch**

1. Finch 使用 `brew` CLI 安裝 。如果出現提示，請輸入您的 macOS 密碼。

   ```
   $ brew install finch
   ```

1. 檢查安裝的Finch版本。

   ```
   $ finch --version
   ```

1. 初始化Finch虛擬機器 （第一次設定）。

   ```
   $ finch vm init
   ```

1. 啟動Finch虛擬機器。

   ```
   $ finch vm start
   ```

1. 檢查Finch虛擬機器的狀態。

   ```
   $ finch vm status
   ```

1. 驗證 是否正確Finch執行。

   ```
   $ finch --info
   $ finch ps
   ```

如需詳細資訊，請參閱[在 macOS 上安裝 Finch](https://runfinch.com/docs/managing-finch/macos/installation/)。

#### Linux
<a name="install-finch-instructions-linux"></a>

您可以在 Finch Amazon Linux、Ubuntu 或使用一般安裝方法來安裝 。如需詳細資訊，請參閱在 [Linux 上安裝 Finch](https://runfinch.com/docs/managing-finch/linux/installation/)。

## Finch 使用 CLI AWS SAM 設定
<a name="install-finch-configuration"></a>

安裝 之後Finch，CLI AWS SAM 會自動偵測 ，並在 Docker 未執行時使用 Finch做為容器執行時間。

**注意**  
Finch 做為 的後援Docker。如果您同時安裝 Docker 和 Finch 並執行 ， AWS SAM CLI Docker 預設會排定優先順序。

### 管理員偏好設定組態 (macOS)
<a name="install-finch-configuration-preference"></a>

您可以透過建立管理員偏好設定檔案，將 AWS SAM CLI 設定為使用特定容器執行期做為預設值。此全系統偏好設定會覆寫預設的備用行為。

**可用的組態選項**
+ **Finch設定為偏好的容器執行時間：**

  ```
  $ sudo /usr/libexec/PlistBuddy -c "Add :DefaultContainerRuntime string finch" /Library/Preferences/com.amazon.samcli.plist
  ```
+ **Docker設定為偏好的容器執行時間：**

  ```
  $ sudo /usr/libexec/PlistBuddy -c "Add :DefaultContainerRuntime string docker" /Library/Preferences/com.amazon.samcli.plist
  ```
+ **移除偏好設定 （返回預設行為）：**

  ```
  $ sudo /usr/libexec/PlistBuddy -c "Remove :DefaultContainerRuntime" /Library/Preferences/com.amazon.samcli.plist
  ```

**注意**  
未設定管理員偏好設定時， AWS SAM CLI Docker 預設會在可用時使用 ，在 Docker 未執行時將 Finch作為備用。

### 目錄掛載差異 (macOS)
<a name="install-finch-differences"></a>

在 macOS 上，如果您在主目錄 (`~`) 或 之外找到專案， AWS SAM 本機命令會失敗`/Volumes`。基於安全考量，此設計會限制自動掛載目錄，而無需您了解。

**緩解選項**
+ **選項 1：**在文字編輯器中開啟 Finch 組態`~/.finch/finch.yaml`，並在 `additional_directories`區段下新增專案路徑，然後重新啟動Finch虛擬機器。如需詳細資訊，請參閱 [Finch 文件](https://runfinch.com/docs/managing-finch/macos/disk-management/#adding-additional-disk-mounts)。

  ```
  $ finch vm stop
  $ finch vm start
  ```
+ **選項 2：**將專案移至主目錄。

## 驗證安裝
<a name="install-finch-verification"></a>

安裝並啟動 後Finch，請確認它是否可與 CLI AWS SAM 搭配使用。

### 基本驗證
<a name="install-finch-verification-basic"></a>

執行下列命令，以確認 AWS SAM CLI 可以使用 Finch：

```
$ sam build --use-container
```

您應該會看到使用 AWS SAM 在容器環境中建置應用程式的 Finch CLI。

**注意**  
Finch 做為 的後援Docker。如果 Docker 執行中， AWS SAM CLI Docker 預設會排定優先順序。

### Finch 測試為備用
<a name="install-finch-verification-fallback"></a>

若要Docker在 執行時測試Finch為備用，您必須先停止Docker。

**測試Finch備用功能**

1. 停止為您的作業系統Docker使用適當的命令。

   **macOS：**

   ```
   $ docker stop $(docker ps -q)
   $ pkill -f "Docker Desktop"
   ```

   驗證 Docker 已停止。

   ```
   $ docker ps
   ```

   **Linux**︰

   ```
   $ docker stop $(docker ps -q)
   $ sudo systemctl stop docker
   ```

   驗證 Docker 已停止。

   ```
   $ sudo systemctl status docker
   ```

1. 執行 `sam build --use-container`命令來驗證 CLI AWS SAM 會自動使用 Finch做為備用。

## 停用 Finch
<a name="install-finch-stopping"></a>

如果您需要停止 Finch，請使用下列命令：

**macOS：**

```
$ finch vm stop
$ sudo pkill -f finch
```

驗證 Finch 已停止。

```
$ finch vm status
```

**Linux**︰

```
$ sudo systemctl stop finch
$ sudo pkill -f finch
```

驗證 Finch 已停止。

```
$ sudo systemctl status finch
```

## 疑難排解
<a name="install-finch-troubleshooting"></a>

如果您遇到 問題Finch：
+ 確認您的作業系統符合先決條件。
+ 確認您已在系統上啟用虛擬化。
+ 對於 macOS，請確認您有足夠的磁碟空間可供虛擬機器使用。
+ 對於 Linux，請確認您具有執行`systemctl`命令的適當許可。
+ 如果您在將多架構映像推送至 Amazon Elastic Container Registry (Amazon ECR) 時遇到「不支援媒體類型」錯誤的 CloudFormation 部署失敗，請建立單一映像成品，而不是使用多架構映像。這是因為 會將影像索引和影像同時Finch推送至 Amazon ECR，而 只會Docker推送影像。
+ 如果跨平台建置在目標函數架構與 Linux 上的主機機器架構不相符時失敗，請執行 來啟用跨平台模擬`sudo finch run --privileged --rm tonistiigi/binfmt:master --install all`。

如需其他疑難排解，請參閱 [Finch 文件](https://runfinch.com/docs/)或 [AWS SAM CLI 故障診斷](sam-cli-troubleshooting.md)。

## 後續步驟
<a name="install-finch-next-steps"></a>

現在Finch已安裝 ，您可以將它與 AWS SAM CLI 搭配使用，以：
+ 使用容器搭配 建置無伺服器應用程式`sam build --use-container`。如需詳細資訊，請參閱[sam build](sam-cli-command-reference-sam-build.md)。
+ 使用 在本機測試 Lambda 函數`sam local invoke`。如需詳細資訊，請參閱[sam local invoke](sam-cli-command-reference-sam-local-invoke.md)。
+ 使用 啟動本機 API Gateway`sam local start-api`。如需詳細資訊，請參閱[sam local start-api](sam-cli-command-reference-sam-local-start-api.md)。
+ 使用 啟動本機 Lambda 端點`sam local start-lambda`。如需詳細資訊，請參閱[sam local start-lambda](sam-cli-command-reference-sam-local-start-lambda.md)。

如需搭配容器使用 AWS SAM CLI 的詳細資訊，請參閱 [使用 的預設建置 AWS SAM](serverless-sam-cli-using-build.md)。