安装Finch以与 AWS SAM CLI 配合使用 - AWS Serverless Application Model
安装 Finch使用 AWS SAM CLI 来配置 Finch验证安装停止 Finch问题排查后续步骤

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

安装Finch以与 AWS SAM CLI 配合使用

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

注意

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

安装 Finch

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

先决条件

注意

Finch在 macOS AWS SAM 和 Linux 系统上可以集成到 CLI 中。对于 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。

使用 AWS SAM CLI 来配置 Finch

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

注意

Finch 充当 Docker 的备用方案。如果您同时Finch安装Docker并运行两者， AWS SAM CLI 会Docker默认设置优先级。

管理员首选项配置 (macOS)

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

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

缓解选项

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

    $ finch vm stop
$ finch vm start

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

验证安装

安装并启动后Finch，请验证它是否可以与 AWS SAM CLI 配合使用。

基本验证

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

$ sam build --use-container

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

注意

Finch 充当 Docker 的备用方案。如果Docker正在运行， AWS 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命令以验证 AWS 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) Container Registry 时遇到 CloudFormation 部署失败并出现 “不支持媒体类型” 错误，请创建单个映像项目，而不是使用多架构映像。之所以出现这种情况，是因为 Finch 会同时将映像索引和映像推送至 Amazon ECR，而 Docker 仅推送映像本身。

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

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

后续步骤

现在您已经Finch安装完毕，可以将其与 AWS 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。

有关在容器中使用 AWS SAM CLI 的更多信息，请参阅默认版本使用 AWS SAM。