AWS Emulator 是亚马逊云科技在 2026 年 11 月 11 日正式推出的本地模拟器。它在你自己的电脑或持续集成环境里提供一套 AWS 风格的 API 端点,AWS CLI 和官方 SDK 用同样的调用方式说话,但请求不会发到云上,也不需要 AWS 账号。官方写明:模拟器本身没有额外服务费,只有你后来把应用部署到 AWS 时,才为真实资源付费。主体源码在 GitHub 上以 CC0 1.0 发布,vendor/ 目录中的代码另按 Apache 2.0 许可。这篇按官方文档走一遍:Linux 安装、把 CLI 指到本地、用官方示例测 S3 和 DynamoDB,再补上 macOS/Windows 的 Docker 做法、在 GitHub Actions 里跑测试的路径,以及它和 LocalStack 该怎么选。

它能替你省掉什么
写会调用 S3 或 DynamoDB 的代码,以前常见的路是:申请账号、配密钥、在云上建资源,或者用一套第三方模拟器。账号和密钥本身就有泄露风险,云上每跑一轮还要等部署、可能产生费用。AWS Emulator 把端点放到本机的 https://127.0.0.1:9297(默认只监听本机),启动时自己生成密钥、配置和证书,写到 ~/.aws/emulator/9297/。访问密钥 ID 以 EMULATOR 开头,不会和真的 AWS 密钥搞混;它也只接受这组密钥签过的请求。
官方把它的典型用途写成三类:本机测试、CI/CD 里的集成测试,以及给编程代理在本地反复调用。它用 Rust 实现,官方博客的说法是为了在笔记本上少占 CPU 和内存;Linux 文档补充,空闲时大约占用 160 MiB,资源存在内存里,用量会随测试创建的对象增长,停止进程后这些对象会被丢掉。
有一件事必须先说清楚:它不是缩小版的 AWS,也不能拿来验证安全策略。官方限制写得很硬:不按 AWS 的方式评估 IAM 和基于资源的策略,一条在云上会被拒绝的请求,在模拟器里可能通过;每个进程只相当于单一账号、单一区域;尚未实现的操作直接返回 HTTP 501(Not Implemented);不要用于生产负载,也不要拿它做安全测试或长时间压测。保真程度按服务和功能而变,官方为每个服务公布「k of n」保真测试通过数,并以公开的 evaluation suite 为准。
在 Linux 上安装并启动
先准备 AWS CLI v2,运行 aws --version 确认可用;安装说明:https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html 。Linux 原生安装要求 64 位 x86_64 或 ARM 系统、glibc 2.17 及以上,可用 ldd --version 查看。macOS 和 Windows 还要先安装 Docker,再走后面的容器步骤。
官方在 Linux 上提供 RPM 和 Debian 包,安装后命令是 aws-emulator,程序位于 /opt/aws-emulator/,命令在 /usr/bin/。先确认机器是 x86_64/amd64 还是 ARM,再选对应包。
Fedora、Amazon Linux 2023 一类用 dnf 的系统(x86_64):
sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm
aws-emulator -v
Debian 或 Ubuntu(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
aws-emulator -v
ARM 机器把文件名换成官方文档里的 aws-emulator-aarch64.rpm 或 aws-emulator_arm64.deb。Amazon Linux 2 用 yum。这些命令装的是 LTS 通道的最新版;要钉死某个版本或在安装前用 GPG 校验签名,官方 Linux 指南里有完整步骤和必须核对的公钥指纹,本文不节选指纹,以免抄错。
在一个终端里启动:
aws-emulator
进程会占住这个终端,默认在 127.0.0.1:9297 提供 HTTPS。日志里会写出地址、配置文件和证书路径,脚本可以依赖这行输出。端口被占用时换一个,例如 aws-emulator -p 9300,或用 -p 0 让系统分配。可以同时开多个进程,各自占用不同端口,状态互不影响。要停掉,在这个终端里按 Ctrl+C,或向进程发 SIGTERM:它会清掉本次在 ~/.aws/emulator/<端口>/ 下生成的文件,以及内存里的全部模拟资源。

把 CLI 和 SDK 指到本地
另开一个终端,先去掉可能指向真实账号的环境变量,再按官方清单导出下面这组变量。端口如果不是 9297,把路径里的数字一起改掉。
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
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
这几项各有用处,不要只抄 AWS_ENDPOINT_URL:
AWS_SHARED_CREDENTIALS_FILE指向模拟器本次生成的密钥。真密钥留在环境变量里的话,请求会被拒绝,因为它只认自己那套以EMULATOR开头的密钥。AWS_CONFIG_FILE会暂时替换你平时的 AWS 配置。模拟器每次启动都会重写这个文件,不要把个人设置写进去;需要额外配置时,先复制一份再改副本路径。AWS_CA_BUNDLE让 AWS CLI、Boto3 和 Go SDK 信任模拟器自己的证书。Java、Node.js、Rust、.NET 还要额外设置,官方「Pointing your AWS SDK at AWS Emulator」页有对照表,例如 Node 用NODE_EXTRA_CA_CERTS,Java 要用同目录下的truststore.p12。AWS_EC2_METADATA_DISABLED避免在 EC2 上跑测试时 SDK 去实例元数据里取真凭证。AWS_DISABLE_HOST_PREFIX_INJECTION避免 CLI 或 Boto3 给主机名加前缀,请求落到不存在的data-127.0.0.1之类地址。这个变量只应出现在对着模拟器的那个 shell 里;用回真实 AWS 时要拿掉,否则部分带主机前缀的操作会失败。
另外,端点必须写成 IP 127.0.0.1,不要改成 localhost:部分 SDK 会把桶名塞进主机名,模拟器不接受这种虚拟主机风格的 S3 请求。S3 Control 一类会强制把账号 ID 加进主机名的 API,官方写明到不了模拟器。
先确认进程已经起来,再看自己是不是真的打到了模拟器:
curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity
健康检查成功时返回 HTTP 200,正文为 ok。官方说明:如果打到了模拟器,调用者账号是 000000000000,ARN 为 arn:aws:iam::000000000000:user/emulator。若这里出现你自己的账号 ID,说明请求还在走 AWS,要回头查环境变量是否在同一个 shell 里生效。
用官方示例测 S3 和 DynamoDB
下面两组命令来自官方博客和文档,不是本文在本机跑出来的结果。你的输出应和官方示例同形;若得到 501,说明当前版本还没实现这个操作,测试应当立刻失败,而不是默默跳过。
创建桶、上传一个小对象并列出(官方博客示例用的桶名是 local-getting-started;文档「What is AWS Emulator?」里另有 amzn-s3-demo-bucket 的 s3api 示例,两种都可以,只要名称合法):
aws s3 mb s3://local-getting-started
echo "hello from the emulator" > hello.txt
aws s3 cp hello.txt s3://local-getting-started/
aws s3 ls s3://local-getting-started/
官方博客里,成功时会看到 make_bucket: local-getting-started 以及把 hello.txt 上传到该桶的提示。
再按官方博客的 DynamoDB 例子建表、写入并读回。表名至少 3 个字符,官方专门演示过:用 ab 做表名时,模拟器会返回和 AWS 相同的 ValidationException。
aws dynamodb create-table --table-name kiro-demo \
--attribute-definitions AttributeName=id,AttributeType=S \
--key-schema AttributeName=id,KeyType=HASH \
--billing-mode PAY_PER_REQUEST
aws dynamodb put-item --table-name kiro-demo \
--item '{"id": {"S": "item-1"}, "msg": {"S": "hello from kiro"}}'
aws dynamodb get-item --table-name kiro-demo --key '{"id": {"S": "item-1"}}'
如果这些命令已经是你现有测试脚本的一部分,只要在启动脚本里先起模拟器、导出同一组环境变量,再跑原来的测试即可,应用代码不必为了本地端点改一遍。官方还提供 Rust SDK 的嵌入模式:在测试进程里直接实例化模拟器,每个实例状态隔离,可以并行跑。那是给 Rust 项目用的第二条路,步骤见官方 embedded mode 文档,这里不展开。

macOS 和 Windows:用 Docker 跑
官方不为 macOS 和 Windows 提供本地安装包,也不发布现成的容器镜像。做法是用文档里那段很短的 Dockerfile,自己把 Linux 包装进镜像再运行。基础镜像是 Amazon Linux 2023 minimal,用 RPM 安装,并把监听地址设成容器内的 0.0.0.0,这样 Docker 才能做端口转发;对外映射仍然只绑 127.0.0.1。Apple silicon 或其它 ARM 机器要把包名换成 aws-emulator-aarch64.rpm。
官方给出的 Dockerfile 如下(x86_64):
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm
RUN rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \
&& mkdir -p /home/emulator && chown 1000 /home/emulator
USER 1000
ENV HOME=/home/emulator
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]
先建目录再构建、启动(macOS / Linux):
mkdir -p ~/.aws/emulator
docker build -t aws-emulator .
PORT=9297
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
-e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
aws-emulator -p $PORT
在 Linux 上跑这个容器时,官方还要求加上 --user "$(id -u):$(id -g)",否则生成的密钥文件可能属于 root,本机 SDK 读不到。Windows PowerShell 的路径和挂载写法见官方 Docker 指南。启动之后,指向模拟器的环境变量和 Linux 本地进程相同,证书路径仍在你挂出来的那个目录里。
网上能找到把官方包打成现成镜像的社区项目,它们自称非官方、与 AWS 无隶属关系。本文只走官方文档的「自行构建」路径,不把第三方镜像当作安装步骤。
在 GitHub Actions 里跑
What’s New 和官方概述都把持续集成写成一等用途:在流水线里跑集成测试,不必准备 AWS 账号,也不必在云上创建资源。官方文档目前没有放一份现成的 GitHub Actions 工作流文件,但 Linux 安装、启动、等健康检查、再导出环境变量,可以直接搬到 Ubuntu 运行器上。将下面的示例保存为仓库中的 .github/workflows/aws-emulator.yml,然后在 GitHub 的 Actions 页面手动运行。它按官方安装步骤改写,不是 AWS 发布的官方 Action;测试命令需要换成你的项目实际使用的命令。
name: AWS Emulator integration
on:
workflow_dispatch:
jobs:
integration:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Install AWS Emulator
run: |
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
- name: Start AWS Emulator
run: |
aws-emulator &
for i in $(seq 30); do
curl -sf --cacert "$HOME/.aws/emulator/9297/ca.pem" \
https://127.0.0.1:9297/__admin/health && break
sleep 1
done
if ! curl -fsS --cacert "$HOME/.aws/emulator/9297/ca.pem" \
https://127.0.0.1:9297/__admin/health; then
echo "AWS Emulator did not become ready" >&2
exit 1
fi
echo "AWS_ENDPOINT_URL=https://127.0.0.1:9297" >> "$GITHUB_ENV"
echo "AWS_SHARED_CREDENTIALS_FILE=$HOME/.aws/emulator/9297/emulator_credentials" >> "$GITHUB_ENV"
echo "AWS_CONFIG_FILE=$HOME/.aws/emulator/9297/config" >> "$GITHUB_ENV"
echo "AWS_CA_BUNDLE=$HOME/.aws/emulator/9297/ca.pem" >> "$GITHUB_ENV"
echo "AWS_EC2_METADATA_DISABLED=true" >> "$GITHUB_ENV"
echo "AWS_DISABLE_HOST_PREFIX_INJECTION=true" >> "$GITHUB_ENV"
echo "AWS_REGION=us-east-1" >> "$GITHUB_ENV"
echo "AWS_DEFAULT_REGION=us-east-1" >> "$GITHUB_ENV"
- name: Run tests
run: make integration-test
把最后一步换成你自己的测试命令。密钥文件是模拟器每次启动新生成的,不要把 EMULATOR 开头的密钥写进仓库,也不要在这个 job 里同时留下真实的 AWS_ACCESS_KEY_ID。官方写过一句很重的提醒:如果跑测试的 shell 里没有设置 AWS_ENDPOINT_URL,代码就会用它找到的任何凭证去调用真的 AWS。CI 密钥泄露会放大这种失误,站内写过 GitHub 上批量盗用账号和 CI 密钥之后该怎么自查,和这条是同一类风险。
Java、Node 等 SDK 在 CI 里还要加上对应的证书环境变量。若测试进程既要访问模拟器、又要访问其它 HTTPS 站点(包括真实 AWS),部分语言里 AWS_CA_BUNDLE 会替换默认证书库,需要按官方说明把模拟器证书追加进系统信任库,而不是直接替换。
限制:哪些测试不要指望它
官方限制集中在「What is AWS Emulator?」和安全说明里,和上手直接相关的是这些:
- 不要测安全。它不按 AWS 的方式评估 IAM 和资源策略,不能用来验证「这条请求该不该被拒绝」。安全相关的结论,必须在真实 AWS 上再测一遍。
- 单一账号、单一区域。它会接受请求里的各种区域和账号 ID,但不会按区域或账号隔离资源。对同一个进程,始终使用同一组区域和账号。要测多个区域,就在不同端口上再开几个进程。
- 保真程度不齐。官方只在
us-west-2(全球性服务则在us-east-1)对照真实 AWS 做过核验,其它区域的功能差异不会反映出来。每个服务公布的是通过了多少条保真测试,分数可能随测试集扩大而下降,官方把它称为改进中产品的快照,不是营销评分。 - 未实现就是 501。遇到尚未实现的操作会立刻失败,这是设计,不是故障。
- 状态只在内存里。空闲约 160 MiB,上限取决于你的机器;进程结束,资源就没了。官方还说没有针对长时间运行或压测做过验证,测完就停,或使用
--idle-timeout让它空闲后自己退出。 - 默认可能发送匿名用量和错误数据,可以关闭。具体开关以当前版本的命令参考为准。
和 LocalStack 怎么选
LocalStack 是更早出现、社区里很常见的 AWS API 模拟器。2026 年它对免费档做了收紧。根据 LocalStack 自己的定价页、服务条款和 2026.03.0 发行说明:免费 Hobby 计划面向个人、教育和其它非商业用途,需要注册账号,从 2026.03.0 起启动时要提供 auth token;Hobby 禁止商业用途,商业开发应使用付费的 Base、Ultimate 或 Enterprise。Hobby 宣传提供 30 多项模拟服务,以及个人沙箱、在 CI 中跑测试等能力。开源项目和部分学生计划另有免费许可,需按官方条件申请,不能把 Hobby 理解成「公司项目也可以免费用」。
两边不是简单的替代关系,更像两条不同的约束:
| AWS Emulator | LocalStack(Hobby / 付费) | |
|---|---|---|
| 费用与许可 | 模拟器无额外服务费,源码 CC0 1.0 | Hobby 免费但限非商用且需注册;商业使用需付费档 |
| 要不要云账号 | 不需要 AWS 账号 | 不需要 AWS 账号,但要 LocalStack 账号和 token |
| 安装 | Linux 官方包;macOS/Windows 需按官方 Dockerfile 自建镜像 | 常见是官方容器镜像,生态和文档更早就位 |
| 行为依据 | 由 AWS 公开的 API 模型生成,并以官方保真测试对照真实 AWS | 长期第三方模拟,服务覆盖以套餐为准 |
| 安全策略 | 官方明确不评估 IAM,不能用来测安全 | 不同套餐能力不同,不能默认等同于真实 IAM |
| 未实现操作 | 返回 501,测试应失败 | 以当前版本实际行为为准 |
若你正在写个人项目、开源测试或公司里还没决定买 LocalStack,又希望尽量贴近官方 API 形状,AWS Emulator 的许可更松,也没有「免费档不能商用」这一条。若团队已经把 LocalStack 嵌进现有流水线,并且需要它已付费覆盖的那些服务或持久化能力,不必为了「官方」两个字强行迁移;先拿你最常用的那几条 API 对照 AWS Emulator 的保真分数,比看宣传名单有用。无论选哪边,上线前都要在真实 AWS 上再跑一遍关键路径,尤其是权限和跨账号、跨区域的逻辑。
背景:这套代码是代理写的
AWS 官方博客写明:模拟器由代理根据公开的 AWS API 模型构建和维护,运行在 Amazon Bedrock AgentCore、CodePipeline 和 CodeCommit 上。一组代理对照真实 AWS 和 Smithy 模型找缺口并开 issue,另一组实现并评审,通过保真测试后再推到公开仓库。安全方面,官方说有独立的安全代理在修改过程中和发布流水线里做对抗式检查;这是厂商自己的流程说明,不是第三方审计结论。
GeekWire 在 2026 年 11 月 11 日的报道里,引述 AWS 高级首席工程师 Matt Goldberg 的话:模拟器完全由自主代理编写,「我们的团队没有写过,也没有审过其中任何一行代码」。报道还说它覆盖 200 多个服务、400 多个 API 模型,项目始于用编程代理在周末先做出一版 SQS 的实验。这些数字和过程细节来自这篇报道及其中引用的工程文章,不是本文核对过的官方规格表;判断能不能用于你的项目,仍以官方保真测试和 501 行为为准。
对使用者,这件事的实际影响是:更新会比较勤(官方说一天可以多次),但你也要把「代码由代理生成、人工未审」放进信任判断里。官方把安全责任写成共担——默认只监听本机、拒绝非自身密钥的请求,是他们为了在你机器上较安全地运行所做的设计;你仍然要决定它跑在哪、放进什么数据,以及生产前如何在 AWS 上复测。源码公开且以 CC0 发布,至少可以自己看、自己改,也可以把版本钉死后再升级。
相关链接
官方博客:https://aws.amazon.com/blogs/aws/test-your-applications-against-aws-locally-with-aws-emulator/
What’s New:https://aws.amazon.com/about-aws/whats-new/2026/11/aws-emulator-now-available/
使用指南:https://docs.aws.amazon.com/emulator/latest/userguide/what-is-service.html
源码(CC0 1.0):aws/aws-emulator
保真测试套件:aws/aws-emulator-evaluation-suite
安装前置条件:https://docs.aws.amazon.com/emulator/latest/userguide/setting-up.html
SDK 端点与证书:https://docs.aws.amazon.com/emulator/latest/userguide/point-sdk-to-emulator.html
Docker 指南:https://docs.aws.amazon.com/emulator/latest/userguide/getting-started-docker.html
LocalStack 定价与许可范围:https://www.localstack.cloud/pricing
LocalStack 2026.03.0 变更:https://blog.localstack.cloud/localstack-for-aws-release-2026-03-0/