- Published on
AWS Emulator:本地模拟AWS API的开源工具
- Authors
- Name
- super_linear
- github.com

概述
AWS Emulator 是亚马逊云科技(AWS)官方发布的一款本地模拟器,用于在开发、测试和持续集成(CI)环境中模拟 AWS API 的行为。它允许开发者在不连接真实 AWS 服务、不创建 AWS 账户的情况下,使用模拟的资源进行代码测试。所有请求都发送到本地运行的模拟器,而非 AWS 云端,因此不会产生任何 AWS 资源费用。该模拟器是一个无图形界面的本地程序,启动后通过设置环境变量即可让 AWS CLI 或 SDK 指向其端点,从而像操作真实 AWS 一样运行代码。此外,它还支持嵌入式模式,特别适合 Rust 项目的单元测试,无需配置端点 URL 或证书。
快速开始
使用 AI 编码助手
如果使用 AI 编码助手(如 Amazon Q Developer),可以安装 aws-emulator 技能,然后让助手自动设置模拟器。这需要 AWS CLI 2.35.0 或更高版本。具体命令为:
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1
服务器模式(CLI 和任何 SDK)
- Linux:安装 RPM 或 Debian 包,然后运行
aws-emulator命令。 - Windows / macOS:通过 Docker 运行模拟器,使用官方提供的 Dockerfile 构建容器。
启动模拟器后,通过设置环境变量(如 AWS_ENDPOINT_URL)将 SDK 指向模拟器端点。详细步骤可参考官方文档中的“Pointing your AWS SDK at AWS Emulator”部分。
嵌入式模式(Rust 测试)
对于 Rust 项目,可以将模拟器作为开发依赖(dev-dependency)添加到 Cargo.toml 中,然后在测试代码中创建模拟器实例,每个测试用例使用独立的隔离实例。这种方式无需设置端点 URL、证书或环境变量,测试代码直接通过模拟器提供的 HTTP 客户端与 SDK 交互。示例代码:
use aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions, Telemetry};
fn main() {
let emulator = AwsEmulatorEmbedded::new(
EmbeddedOptions::default().telemetry(Telemetry::Off)
);
let _http_client = emulator.http_client();
}
已知问题与保真度
AWS Emulator 并非完美复制所有 AWS API 行为。每个版本发布时都会附带一份“保真度评分”(fidelity scores),用于说明各个服务与真实 AWS 的匹配程度。用户可以通过查看发布页面上的评分来了解当前模拟的准确度。此外,仓库的 issues/ 目录下记录了已知的差距:issues/things-that-do-not-work/ 存放尚未实现的功能,issues/things-that-now-work/ 存放已修复的问题。如果用户发现自己的项目无法正常工作,可以参考官方文档“Checking whether your project works with AWS Emulator”进行排查。
从源码构建
适用场景
- 修改模拟器代码
- 从 Git 检出运行
- 使用嵌入式模式(嵌入式模式会将模拟器编译进测试二进制文件,因此构建成本与从源码构建相同)
大多数用户应直接使用预构建包(参见快速开始部分)。从源码构建仅支持 Linux(x86_64 和 aarch64),Windows 和 macOS 用户请使用 Docker 方式。
前提条件
- Rust 工具链(通过 rustup 安装)
- C 编译器(如 GCC 或 clang),因为部分依赖需要编译 C 代码
- 至少 100 GB 可用磁盘空间用于
target/目录(工作区包含每个 AWS 服务一个 crate,调试构建体积庞大,且会随服务增加而增长) - 多核机器(首次完整构建需要编译所有服务 crate,核心数越少耗时越长)
构建与运行
cargo build -p aws-emulator-router
cargo run -p aws-emulator-router
模拟器将在 127.0.0.1:9297 上提供 HTTPS 服务(使用自签名证书)。
嵌入式模式构建成本
嵌入式模式会将模拟器编译进测试二进制文件,因此首次运行 cargo test 时会同时编译模拟器的所有服务 crate 和用户代码。首次构建的时间和磁盘占用与从源码构建相当,但后续增量构建会很快。建议:
- 在多个项目间复用同一个
CARGO_TARGET_DIR - 在 CI 中缓存
target/目录或使用 sccache - 将模拟器固定到某个发布版本,避免每次变更都重新构建
仓库布局
.
├── Cargo.toml # 工作区定义,每个服务一个成员,加上核心 crate
├── services/
│ └── service-<name>/ # 每个 AWS 服务一个 crate
│ ├── smithy-model/ # <name>.json — 驱动线协议的 Smithy 模型
│ ├── build.rs # 从模型生成服务声明
│ ├── src/
│ │ ├── service.rs # 请求路由和拒绝覆盖
│ │ ├── state.rs # 该服务的内存状态
│ │ └── ops/ # 每个操作一个文件
│ └── tests/
├── core/
│ ├── router/ # 模拟器二进制:将所有服务挂载到一个端点
│ └── embedded/ # 进程内(嵌入式模式)外观
├── vendor/ # 框架 crate — 请勿编辑(更新时会被替换)
└── issues/ # 跟踪的保真度问题
遥测
AWS Emulator 默认启用遥测,用于收集使用数据以改进产品。遥测遵循严格的数据最小化原则,不会识别或关联到特定用户、账户或组织。记录中绝不包含请求/响应内容、代码、凭证或个人数据。数据不会与第三方共享。
关闭遥测的方法
- 命令行选项:启动时添加
--telemetry off(或-t off),仅对当前进程生效。aws-emulator --telemetry off - 环境变量:设置
EMULATOR_TELEMETRY=off,对当前 shell 启动的所有模拟器生效。
可接受的值:export EMULATOR_TELEMETRY=off aws-emulatoron/true/1开启,off/false/0关闭,不区分大小写。其他值会关闭遥测并显示警告。 - 配置文件:在
~/.aws/emulator/config.toml(Linux/macOS)或%USERPROFILE%\.aws\emulator\config.toml(Windows)中添加:
可通过[telemetry] enabled = falseEMULATOR_CONFIG环境变量指定其他路径。 - 嵌入式 API:在创建模拟器时通过
Telemetry::Off选项关闭。
如果开发者构建的工具中包含了模拟器,应告知用户遥测的存在并提供关闭方式,也可以默认关闭遥测。
报告问题与贡献
- 报告问题:请在 GitHub Issues 中提交,最好包含服务名称、操作、SDK 版本、发送的请求以及响应与真实 AWS 的差异。
- 贡献:该仓库不接受 Pull Request。
许可证
- 除
vendor/目录外,代码采用 CC0 1.0 通用许可证(CC0-1.0)。 vendor/目录下的代码采用 Apache License 2.0。
详细内容请参阅仓库中的 LICENSE 文件和 vendor/README.md。
总结
AWS Emulator 为开发者提供了一个免费、本地化的 AWS API 模拟环境,支持多种使用方式(CLI、Docker、嵌入式),并提供了详细的保真度追踪和灵活的遥测控制。尽管首次构建成本较高,但其增量编译和缓存策略可以显著提升开发效率。对于需要频繁测试 AWS 集成代码的团队,这是一个值得尝试的工具。
原标题:AWS emulator。 HN 原始发布时间:2026年11月12日星期四。当前记录为 968 分、264 条评论。