本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

Finch是 AWS的容器开发工具，它提供了一种替代方案Docker，对macOS和Linux系统特别有用。有关更多信息，请参阅 [Finch on。 GitHub](https://github.com/runfinch)使用Finch， AWS SAM 可以提供类似于容器的本地环境 AWS Lambda ，用于构建、测试和调试您的无服务器应用程序。

**注意**  
您需要 Finch 来本地测试应用程序、使用 `--use-container` 选项构建部署包以及构建 OCI 映像函数。从 AWS SAM CLI 版本 1.145.0 开始，CL AWS SAM I 支持Finch将其作为替代容器运行时。Docker

**Topics**
+ [安装 Finch](#install-finch-instructions)
+ [使用 AWS SAM CLI Finch 进行配置](#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在 macOS AWS SAM 和 Linux 系统上可以集成到 CLI 中。对于 Windows 用户，建议使用虚拟机或 Linux 环境来实现 Finch 功能。

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

**注意**  
Finch 支持最新两个版本的 macOS。

**Linux：**
+ Linux Kernel v4.x\+

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

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

**在 macOS 上安装 Finch**

1. 使用 `brew` CLI 来安装 Finch。如果出现提示，请输入您的 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>

您可以在 Amazon Linux、Ubuntu 上安装 Finch，或使用通用安装方法进行安装。有关更多信息，请参阅[在 Linux 上安装 Finch](https://runfinch.com/docs/managing-finch/linux/installation/)。

## 使用 AWS SAM CLI Finch 进行配置
<a name="install-finch-configuration"></a>

安装后Finch， AWS SAM CLI 会自动检测Docker未运行的容器运行时并将其Finch用作容器运行时。

**注意**  
Finch 充当 Docker 的备用方案。如果您同时Finch安装Docker并运行两者， 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
  ```

**注意**  
如果未设置管理员首选项，则Docker默认情况下， AWS SAM CLI 在可用时使用，在未运行时FinchDocker作为后备选项。

### 目录挂载差异 (macOS)
<a name="install-finch-differences"></a>

在 macOS 上，如果将项目放在主目录之外 (`~`) 或，则 AWS SAM 本地命令会失败。`/Volumes`此设计出于安全考虑，会在您不知情的情况下，限制目录的自动挂载功能。

**缓解选项**
+ **选项 1：**在文本编辑器 `~/.finch/finch.yaml` 中打开 Finch 配置，在 `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，请验证它是否可以与 AWS SAM CLI 配合使用。

### 基本验证
<a name="install-finch-verification-basic"></a>

运行以下命令以验证 AWS SAM CLI 是否可以使用Finch：

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

你应该看到 AWS SAM CLI Finch 是用来在容器环境中构建应用程序的。

**注意**  
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`命令以验证 AWS SAM CLI 是否自动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) Container Registry 时遇到 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)。
+ 使用 `sam local invoke` 在本地测试 Lambda 函数。有关更多信息，请参阅 [sam local invoke](sam-cli-command-reference-sam-local-invoke.md)。
+ 使用 `sam local start-api` 来启动本地 API Gateway。有关更多信息，请参阅 [sam local start-api](sam-cli-command-reference-sam-local-start-api.md)。
+ 使用 `sam local start-lambda` 来启动本地 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)。