AWS 本地测试怎么做：官方仿真器加五条回真云的红线

AI 编程智能体改云上代码，每验一轮都要真部署：等几十秒到两分钟、要花钱、还可能弄脏共享开发账号。AWS 11 月 11 日放出的本地仿真器把这一段搬回了本机，但它只过了一半保真测试——所以要解决的不是"装不装"，而是"哪些结论能算数"。

先算账：它省掉的是「验证」这一步，不是「云」

智能体的循环是这样的：改一版、跑测试、读报错、再改。这个循环里最慢的环节不是写代码，是验证——部署要等，资源要钱，跑完还要清理。AWS 给出的理由很直接：智能体产出代码的速度，已经超过团队在真云里验证的速度。

AWS Emulator 就是奔着这一段来的。它是一个无界面的本地程序，在本机起一个 HTTPS 端点，AWS CLI、各家 SDK、以及智能体都按原来的方式调用，代码一行不改，只改环境变量。

几个数字先记住：规模是 200 多个服务，由 438 个 Smithy API 模型生成；端点默认 https://127.0.0.1:9297，只绑回环地址；资源全在内存，进程一停就没了；只有一个账号 000000000000；许可是 CC0，vendor/ 目录除外。

它和 LocalStack 不是一回事。LocalStack 今年把免费档挪到了账号后面，并限制在非商业用途。AWS 这个不要账号、不要令牌、不收费，但它把"不完全像"的地方摆在了明面上——每个版本发布都附一份按服务统计的保真度，跑不通的接口直接返回 501。

所以正确的期待是：它替换的是"请求形状、错误码、基本状态流转对不对"，不替换"策略、配额、区域、编排"。 这条界线就是后半段的重点。

装起来：三步，然后先证明你真的切过去了

第一步，装。 Linux 给的是 RPM 与 Debian 包。官方演示用的是 Amazon Linux 2023：

PKG=https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest
sudo dnf install -y $PKG/aws-emulator-x86_64.rpm
aws-emulator -v

Debian 包在同一个目录下，按发行版取对应文件即可。macOS 和 Windows 没有安装包，也没有现成镜像，官方要求用文档里那份很短的 Dockerfile 自己构建。在 Windows 上不想折腾容器的话，WSL2 里按发行版装包是更接近官方验证环境的路子——这是我的取舍，不是官方建议。

第二步，起进程，然后在一个专用 shell 里设变量。

aws-emulator --telemetry off

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_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

最后那行 unset 是安全边界，不是可选步骤。仿真器每次启动都会重新生成密钥，访问密钥 ID 一律以 EMULATOR 开头，用它签名的请求才会被接受；但只要 shell 里还留着真实凭证，某些工具链就会绕过 credentials 文件去读环境变量。宁可多开一个终端，也不要在日常那个终端里做实验。

第三步，证明切成功了。 别假设 export 生效——IDE 内置终端、CI 的每个 step、sudo 之后的 shell 都不一定继承。

curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity

第二行应该返回账号 000000000000。看到真实的十二位账号 ID，说明你还在连真 AWS，停手检查变量。确认之后再跑冒烟：

aws s3 mb s3://local-getting-started
aws s3 cp hello.txt s3://local-getting-started/
aws s3 ls s3://local-getting-started/

主力是编程智能体的话，可以让它自己完成安装与连接：aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1，需要 AWS CLI 2.35.0 及以上。这个 skill 会装、起、连，还会检查当前项目能不能跑在仿真器上；它属于哪一种工具形态，这篇从补全到智能体的四个层级讲得更细。

一句提醒：skill 也是供应链。装之前看清来源是官方仓库，装完扫一眼它到底执行了哪些命令。同类问题在插件投毒那次已经演示过一遍，别把第三方扩展当成不需要读的 npm 包。

按服务分档：哪些「本地绿了」能算数

AWS 每个版本发布都会附上分服务的保真度，测试本身也公开在 evaluation suite 仓库里。按发布包 v1.0.322 的计分测试统计，42,857 条里过了 24,243 条，约 56.6%——这个总账是社区按 scores 文件汇总的，不是 AWS 官方口径，但足够说明问题：一半以上的行为对得上，另一半不能假设。

有一点要说清：不同版本、不同统计口径会有差异，同样这几个服务，另一份按测试单元汇总的数据给 CloudFormation 记的是 36%。以你手上那个版本的 scores 为准，别拿二手汇总当合同。另外，这批量测试的行为基准是 us-west-2，全球服务除外。

501 是这套工具里最值得记住的返回值。它表示"这个操作还没实现"，不是"你的代码写错了"。

区分方法很朴素：501 别改代码，改也没用；400、403、ValidationException 才是该动手的地方。DynamoDB 用两个字符的表名建表会返回和真 AWS 一模一样的 ValidationException 文本——这类逐字一致的报错，才是本地测试真正的价值。

五条红线：这些结论只能回真云下

红线一：IAM 与资源策略。 官方在仓库里写得很清楚：不要用它测安全。仿真器不做策略求值，真 AWS 会拒绝的请求，本地可能一路成功。权限 bug 就是这样溜过去的——本地全绿，上线第一个 403。能力边界该怎么切，四道闸那篇给过一套办法。

红线二：跨账号与跨区。 只有一个账号 000000000000，资源也不按区域隔离。要验多区行为，就一区起一个实例、各占一个端口，别指望一个进程模拟出两地的差异。

红线三：配额、限流与故障。 节流、服务中断、区域功能差异都不模拟。这类问题只能在真账号上跑，或者用专门的故障注入手段，仿真器在这件事上帮不上忙。

红线四：编排类。 CloudFormation、CDK 生成的变更集，保真度是全表最低的一档。模板能不能过语法检查可以本地看，变更会怎么落地、失败怎么回滚，别在这里下结论。

红线五：凭证与数据。 专用 shell、不挂生产凭证、不把真实用户数据灌进仿真器。遥测默认开着，AWS 说只收匿名使用与错误数据、不含请求响应内容；介意就 --telemetry off，或在 ~/.aws/emulator/config.toml 里写 [telemetry] enabled = false。

规则写进文档才算数。下面这段可以直接贴进 CLAUDE.md 或 AGENTS.md：

## 云上代码的验证规则
1. 单服务、单请求的接口形状与错误码，先在本地仿真器跑：
   端点 https://127.0.0.1:9297，账号 000000000000。
2. 遇到 501 Not Implemented：停下来，在结论里注明"仿真器未实现"。
   不要为了跑通去改业务代码、加兜底分支或换实现。
3. 涉及 IAM 策略、跨账号、跨区、配额、限流、CloudFormation/CDK 变更集：
   不要在本地下结论。产出一份待人工执行的命令清单，标出预期结果。
4. 每轮改完输出两列：本地已验证 / 只能在真云验证。
   缺第二列视为未完成。

最后是验收节奏。资源在内存里，进程停就清空，所以 CI 里每次跑完直接结束进程，不要让测试之间共享状态。

上线前用同一套测试在真账号再跑一遍，两次结果不一致时以真云为准，并把这个差异记进 issue——你遇到的那条 501 或那段不一致的报错，正是这份工具最需要你回报的东西。

工具的价值从来不在"替代云"。它只是把不值得上云验证的部分挡在了本机，剩下的部分，该付费还是要付费。