安装 Finch 以与 Amazon SAM CLI 一起使用 - Amazon Serverless Application Model
安装 Finch使用 Amazon SAM CLI 来配置 Finch验证安装停止 Finch故障排除后续步骤
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

安装 Finch 以与 Amazon SAM CLI 一起使用

Finch 是 Amazon 的容器开发工具，为 Docker 提供替代方案，尤其适用于 macOS 和 Linux 系统。有关更多信息，请参阅 GitHub 上的 Finch。凭借 Finch，Amazon SAM 可以提供类似于 Amazon Lambda 的本地环境作为容器来构建、测试和调试您的无服务器应用程序。

注意

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

安装 Finch

请按照以下说明在您的操作系统上安装 Finch。

先决条件

注意

Finch 在 Amazon SAM CLI 中的集成可在 macOS 和 Linux 系统上使用。对于 Windows 用户，建议使用虚拟机或 Linux 环境来实现 Finch 功能。

macOS 版本：

  • macOS 15 Sequoia

  • macOS 14 Sonoma

注意

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

（Linux）：

  • Linux Kernel v4.x+

安装 Finch

在 macOS 上安装 Finch

  1. 使用 brew CLI 来安装 Finch。如果出现提示，请输入您的 macOS 密码。

    $ brew install finch

  2. 检查已安装的 Finch 版本。

    $ finch --version

  3. 初始化您的 Finch 虚拟机（首次设置）。

    $ finch vm init

  4. 启动Finch 虚拟机。

    $ finch vm start

  5. 检查 Finch 虚拟机的状态。

    $ finch vm status

  6. 确认 Finch 运行正常。

    $ finch --info
$ finch ps

有关更多信息，请参阅 在 macOS 上安装 Finch。

您可以在 Amazon Linux、Ubuntu 上安装 Finch，或使用通用安装方法进行安装。有关更多信息，请参阅在 Linux 上安装 Finch。

使用 Amazon SAM CLI 来配置 Finch

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

注意

Finch 充当 Docker 的备用方案。若您同时安装并运行 Docker 和 Finch，Amazon SAM CLI 会默认优先使用 Docker。

管理员首选项配置 (macOS)

您可以通过创建管理员首选项文件，将 Amazon 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
注意

当未设置管理员首选项时，Amazon SAM CLI 默认使用可用的 Docker，若 Docker 未运行，则将 Finch 作为备用方案。

目录挂载差异 (macOS)

在 macOS 上，若项目位于您的主目录 (~) 或 /Volumes 之外，Amazon SAM 本地命令将无法正常运行。此设计出于安全考虑，会在您不知情的情况下，限制目录的自动挂载功能。

缓解选项

  • 选项 1：在文本编辑器 ~/.finch/finch.yaml 中打开 Finch 配置，在 additional_directories 部分下添加您的项目路径，然后重启 Finch 虚拟机。有关更多信息，请参阅 Finch 文档。

    $ finch vm stop
$ finch vm start

  • 选项 2：将您的项目移至您的主目录。

验证安装

安装并启动 Finch 后，请验证其能否与 Amazon SAM CLI 协同工作。

基本验证

运行以下命令，以验证 Amazon SAM CLI 可以使用 Finch：

$ sam build --use-container

您应看到 Amazon SAM CLI 正在使用 Finch，在容器环境中构建您的应用程序。

注意

Finch 充当 Docker 的备用方案。如果 Docker 正在运行，Amazon SAM CLI 将默认优先使用 Docker。

测试 Finch 作为备用方案

当 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

  2. 运行 sam build --use-container 命令，以验证 Amazon SAM CLI 是否自动将 Finch 作为备用方案。

停止 Finch

如果您需要停止 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

故障排除

如果您在使用 Finch 时遇到问题：

  • 验证您的操作系统是否满足先决条件。

  • 确认您已在系统上启用虚拟化。

  • 对于 macOS，请确认您有足够的磁盘空间来安装虚拟机。

  • 对于 Linux，请确认您拥有运行 systemctl 命令的适当权限。

  • 如果您将多架构映像推送至 Amazon Elastic Container Registry (Amazon ECR) 时，遇到 Amazon CloudFormation 部署失败问题并显示“媒体类型不受支持”错误，请创建单一的映像构件，而非使用多架构映像。之所以出现这种情况，是因为 Finch 会同时将映像索引和映像推送至 Amazon ECR，而 Docker 仅推送映像本身。

  • 如果在 Linux 环境中，目标函数架构与主机架构不匹配导致跨平台构建失败，请通过运行 sudo finch run --privileged --rm tonistiigi/binfmt:master --install all 来启用跨平台模拟功能。

有关其他故障排除，请参阅 Finch 文档或 Amazon SAM CLI 故障排除。

后续步骤

现在您已安装 Finch，可以将其与 Amazon SAM CLI 结合使用，以便：

  • 使用带 sam build --use-container 的容器构建无服务器应用程序。有关更多信息，请参阅 sam build。

  • 使用 sam local invoke 在本地测试 Lambda 函数。有关更多信息，请参阅 sam local invoke。

  • 使用 sam local start-api 来启动本地 API Gateway。有关更多信息，请参阅 sam local start-api。

  • 使用 sam local start-lambda 来启动本地 Lambda 端点。有关更多信息，请参阅 sam local start-lambda。

有关将 Amazon SAM CLI 与容器结合使用的更多信息，请参阅 使用 Amazon SAM 进行默认构建。