紀錄工作經驗、相關知識,解決技術相關問題。

時事新聞, 資訊相關

AWS Emulator 是什麼?AWS 官方本機模擬器的支援範圍、安裝與限制

AWS Emulator 是什麼?AWS 官方本機模擬器的支援範圍、安裝與限制 特色圖片

AWS Emulator 是 AWS 官方提供、在自己電腦上模擬 AWS API 的程式。程式碼對它發出的請求不會送到 AWS,所以測試時不需要 AWS 帳號,也不會動到真的資源。

這篇依序說明它是什麼、支援哪些服務、怎麼安裝與設定,以及使用前要知道的限制,最後列出它和 LocalStack 兩邊各自公開的資訊。

AWS Emulator 是什麼

AWS 官方文件的說法是:AWS Emulator 是在本機模擬 AWS API 的程式,讓你在不呼叫 AWS 的情況下測試軟體。可以跑在自己的電腦、開發伺服器或 CI(Continuous Integration,持續整合)環境,不需要 AWS 帳號,也沒有額外的服務費用。

它沒有圖形介面,啟動後會提供一個 AWS API 端點。你用環境變數讓 AWS CLI 或 AWS SDK 指到這個端點,程式碼本身不用改。

官方列出的用途有三個:

  • 本機測試:包含跨服務的呼叫。
  • CI/CD 整合測試:不需要 AWS 帳號與 AWS 資源。
  • 搭配 AI 程式碼代理(AI coding agent)做原型開發。

授權方面,原始碼採 CC0 1.0(公眾領域貢獻宣告),vendor/ 目錄內的程式碼則是 Apache License 2.0。

案例:官方模擬器的維護方式

這個專案的維護方式和一般開源專案不同。GitHub README 寫明不接受 pull request,官方文件則說由 AI 代理讓 Emulator 跟上 AWS 服務的變動,更新一天可以有很多次。

發現行為和 AWS 不一樣時,要到 aws-emulator 的 GitHub Issues 回報,附上重現步驟、收到的回應與預期結果。

對使用者來說,這代表版本更新很頻繁,每次 release 的擬真度分數都可能變動,要拿同一個版本的測試集比較(下一節說明)。

支援範圍與限制

官方文件說,AWS API models 倉庫有 API 模型的 AWS 服務,都在支援範圍內。但做到多像真的 AWS,各服務不同,官方稱為「fidelity(擬真度)」。

擬真度怎麼算

官方寫了一批「擬真度測試」:用 AWS SDK 對某個服務跑一段工作流程,斷言 AWS 的結果、最後狀態,以及無效呼叫的確切錯誤。Emulator 對每個服務通過幾項、總共幾項,就是該服務的擬真度分數,例如 50 項通過 40 項。

分數隨每次 release 公布在 GitHub releases 頁面。官方提醒,只有使用同一版測試集的分數才能比較。

尚未實作的操作會回傳 HTTP 501 與錯誤碼 NotImplemented,測試會當場失敗,不會默默通過。

官方也寫明,目前控制平面(control plane,建立、讀取、更新、刪除資源的 API,例如建立 S3 bucket)的擬真度最高。資料平面(data plane,服務的主要功能,例如存取 S3 物件),以及 CloudFormation、Terraform、AWS CDK 的支援,依服務而異。

使用限制

項目官方說明
定位用於開發與測試,不適合正式環境
IAM 與資源型政策不會像 AWS 那樣評估,不能拿來測安全性
Region 與帳號接受任何 Region 與帳號 ID,但不分開存放資源;要測多個 Region 就各開一個 Emulator、各用一個連接埠
驗證範圍行為只拿 us-west-2 比對 AWS(全球服務用 us-east-1),不同 Region 的服務差異沒有反映
資源存放全部在記憶體,停止後資源即清空
長時間使用沒測過長時間執行與壓力測試,建議測完就關閉,或用 --idle-timeout 讓它自己停

資料來源:What is AWS Emulator?、Fidelity in AWS Emulator,內容為整理摘要。

另一個要注意的是平台:Emulator 只有 Linux 是原生執行,macOS 與 Windows 要透過 Docker。

怎麼開始用

官方提供四種方式:

  1. AI 程式碼代理:安裝 aws-emulator skill,由代理幫你安裝、啟動與連線,需要 AWS CLI 2.35.0 以上。
  2. Linux 套件:用 RPM 或 Debian 套件安裝,當本機程序執行。
  3. Docker:Windows、macOS 的路徑,或偏好容器的 Linux。
  4. 內嵌模式:在 Rust 測試程序內執行,每個測試有獨立狀態。

Linux 與 Docker 都在 127.0.0.1 的 9297 連接埠提供 HTTPS 服務。

Linux 套件安裝

Linux 需要 64 位元的 x86_64 或 aarch64 系統,glibc 2.17 以上,可用 ldd --version 查 glibc 版本。以 Debian 系 amd64 為例,官方指令是:

curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator.deb

RPM 系與 arm64 的連結不同,請看官方 Linux 安裝頁。裝完後確認版本:

aws-emulator -v

接著啟動,它會一直在這個終端機執行,按 Ctrl+C 結束:

aws-emulator

預設只聽 127.0.0.1:9297,所以只有本機連得到。9297 被占用時可用 -p 換連接埠,例如 aws-emulator -p 9300。

Docker 安裝

官方沒有提供預先建好的映像檔,要用官方給的 Dockerfile 自己建,裡面是安裝上面的 Linux 套件。Dockerfile 內容與 docker run 指令請看官方 Docker 安裝頁。

官方特別提醒,連接埠要寫成 -p 127.0.0.1:9297:9297,不要寫 -p 9297:9297,後者會讓整個區域網路的其他電腦都連得到 Emulator。

讓 CLI 或 SDK 指向 Emulator

啟動後,Emulator 會產生只在這次執行有效的金鑰與憑證,寫到 ~/.aws/emulator/9297/。接著在跑測試的 shell 設定環境變數。以下是官方列出的前四個:

export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem

完整清單還有 AWS_EC2_METADATA_DISABLED、AWS_DISABLE_HOST_PREFIX_INJECTION、AWS_REGION 等變數,以及 Java、Node.js 各自信任憑證的設定,請看官方的 SDK 設定頁。

這裡最容易出事的地方,官方也標為重要提醒:如果跑測試的 shell 沒有設 AWS_ENDPOINT_URL,程式碼會拿手上找得到的憑證去呼叫真的 AWS。環境變數裡也不要放真實憑證。

要確認有沒有連對,執行:

aws sts get-caller-identity

連到 Emulator 時,Account 會是 000000000000;如果看到自己的帳號 ID,代表請求送到了 AWS。

補充說明:設定 AWS_CONFIG_FILE 會讓那個 shell 不再讀你自己的 AWS config,原本放在裡面的重試、S3 等設定都不會生效。官方建議複製 Emulator 產生的 config、加上自己的設定,再指向複本。

和 LocalStack 的公開資訊對照

LocalStack 是另一個常被拿來比較的本機 AWS 模擬方案。AWS 的 README 沒有提到 LocalStack,所以這一節只整理兩邊各自公開的資訊,不做功能優劣的比較。

項目AWS EmulatorLocalStack
維護方AWSLocalStack
授權CC0 1.0,vendor/ 為 Apache 2.0GitHub repo 的 README 寫 Apache License 2.0,且下載使用即同意 EULA
費用官方說明沒有額外服務費用官方授權頁列出 Hobby(非商業用途)與 Base、Ultimate、Enterprise 等方案
執行方式Linux 原生;macOS、Windows 用 Docker單一容器,需要 Docker 環境;官方文件說明需設定 Auth Token 啟用

LocalStack 的 GitHub repo 在 2026 年 3 月 23 日封存為唯讀,README 說明原因是把開發整併成單一映像檔。對照時請以 LocalStack 官方文件目前的說明為準。

資料來源:aws/aws-emulator、localstack/localstack 的 README、LocalStack Licensing & Tiers、LocalStack Getting Started。

兩者在特定服務上誰做得比較完整,官方沒有提供對照資料,這裡不下結論。

已經在用 LocalStack 的話,可以先照 Emulator 的專案檢查頁的步驟,列出自己呼叫的 AWS 操作,對照擬真度測試與分數,再決定是否換用。

遙測資料

Emulator 預設會傳送匿名的使用與錯誤資料,官方說明內容不含請求與回應內容、憑證、程式碼與個人資料。

要關閉,啟動時加上選項:

aws-emulator --telemetry off

也可以設定環境變數 EMULATOR_TELEMETRY=off。在 Docker 容器內,要用 -e 傳進容器,只在自己的 shell 設定對容器無效。

參考資料與延伸閱讀

發佈留言