安裝 Finch以搭配 CLI AWS SAM 使用 - AWS Serverless Application Model
安裝 FinchFinch 使用 AWS SAM CLI 設定驗證安裝停用 Finch疑難排解後續步驟

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

安裝 Finch以搭配 CLI AWS SAM 使用

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

注意

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

安裝 Finch

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

先決條件

注意

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

macOS 版本：

  • macOS 15 Sequoia

  • macOS 14 Sonoma

注意

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

Linux︰

  • Linux 核心 v4.x+

安裝 Finch

在 macOS 上安裝 Finch

  1. Finch 使用 brew CLI 安裝 。如果出現提示，請輸入您的 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。

您可以在 Finch Amazon Linux、Ubuntu 或使用一般安裝方法來安裝 。如需詳細資訊，請參閱在 Linux 上安裝 Finch。

Finch 使用 AWS SAM CLI 設定

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

注意

Finch 做為 的後援Docker。如果您同時安裝 Docker 和 Finch 並執行 ， 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
注意

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

目錄掛載差異 (macOS)

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

緩解選項

  • 選項 1：在文字編輯器中開啟 Finch 組態~/.finch/finch.yaml，並在 additional_directories區段下新增專案路徑，然後重新啟動Finch虛擬機器。如需詳細資訊，請參閱 Finch 文件。

    $ finch vm stop
$ finch vm start

  • 選項 2：將專案移至主目錄。

驗證安裝

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

基本驗證

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

$ sam build --use-container

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

注意

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命令來驗證 CLI AWS SAM 會自動使用 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) 時遇到「不支援媒體類型」錯誤的 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。

  • 使用 在本機測試 Lambda 函數sam local invoke。如需詳細資訊，請參閱sam local invoke。

  • 使用 啟動本機 API Gatewaysam local start-api。如需詳細資訊，請參閱sam local start-api。

  • 使用 啟動本機 Lambda 端點sam local start-lambda。如需詳細資訊，請參閱sam local start-lambda。

如需搭配容器使用 AWS SAM CLI 的詳細資訊，請參閱 使用 的預設建置 AWS SAM。