AWS Emulator

AWS 模拟器

S3, SQS, IAM, and STS emulation with AWS SDK-compatible S3 paths and query-style SQS/IAM/STS endpoints. All state is in-memory, and responses use AWS-compatible XML.

提供与AWS SDK兼容的S3路径和查询式SQS/IAM/STS端点，实现S3、SQS、IAM和STS服务的模拟。所有状态均存储在内存中，响应采用与AWS兼容的XML格式。

Start

启动

bash

undefined

bash

undefined

AWS only

仅启动AWS模拟

npx emulate --service aws

Default port (when run alone)

默认端口（单独运行时）

http://localhost:4000


Or programmatically:

```typescript
import { createEmulator } from 'emulate'

const aws = await createEmulator({ service: 'aws', port: 4006 })
// aws.url === 'http://localhost:4006'


或者通过编程方式启动：

```typescript
import { createEmulator } from 'emulate'

const aws = await createEmulator({ service: 'aws', port: 4006 })
// aws.url === 'http://localhost:4006'

Auth

认证

Pass tokens as

Authorization: Bearer <token>

. Scoped permissions use

s3:*

,

sqs:*

,

iam:*

,

sts:*

patterns.

bash

curl http://localhost:4006/ \
  -H "Authorization: Bearer test_token_admin"

通过

Authorization: Bearer <token>

传递令牌。权限范围采用

s3:*

、

sqs:*

、

iam:*

、

sts:*

模式。

bash

curl http://localhost:4006/ \
  -H "Authorization: Bearer test_token_admin"

Pointing Your App at the Emulator

将应用指向模拟器

Environment Variable

环境变量

bash

AWS_EMULATOR_URL=http://localhost:4006

bash

AWS_EMULATOR_URL=http://localhost:4006

AWS SDK v3

typescript

import { S3Client } from '@aws-sdk/client-s3'

const s3 = new S3Client({
  endpoint: process.env.AWS_EMULATOR_URL,
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  },
  forcePathStyle: true,
})

typescript

import { SQSClient } from '@aws-sdk/client-sqs'

const sqs = new SQSClient({
  endpoint: `${process.env.AWS_EMULATOR_URL}/sqs`,
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  },
})

typescript

import { IAMClient } from '@aws-sdk/client-iam'

const iam = new IAMClient({
  endpoint: `${process.env.AWS_EMULATOR_URL}/iam`,
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  },
})

typescript

import { S3Client } from '@aws-sdk/client-s3'

const s3 = new S3Client({
  endpoint: process.env.AWS_EMULATOR_URL,
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  },
  forcePathStyle: true,
})

typescript

import { SQSClient } from '@aws-sdk/client-sqs'

const sqs = new SQSClient({
  endpoint: `${process.env.AWS_EMULATOR_URL}/sqs`,
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  },
})

typescript

import { IAMClient } from '@aws-sdk/client-iam'

const iam = new IAMClient({
  endpoint: `${process.env.AWS_EMULATOR_URL}/iam`,
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
    secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
  },
})

Seed Config

初始配置

yaml

aws:
  region: us-east-1
  s3:
    buckets:
      - name: my-app-bucket
      - name: my-app-uploads
        region: eu-west-1
  sqs:
    queues:
      - name: my-app-events
      - name: my-app-dlq
        visibility_timeout: 60
      - name: my-app-orders.fifo
        fifo: true
  iam:
    users:
      - user_name: developer
        create_access_key: true
      - user_name: readonly-user
    roles:
      - role_name: lambda-execution-role
        description: Role for Lambda function execution
        assume_role_policy: '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}'

Default seed (always created): S3 bucket

emulate-default

, SQS queue

emulate-default-queue

, IAM user

admin

with access key pair (

AKIAIOSFODNN7EXAMPLE

/

wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

).

yaml

aws:
  region: us-east-1
  s3:
    buckets:
      - name: my-app-bucket
      - name: my-app-uploads
        region: eu-west-1
  sqs:
    queues:
      - name: my-app-events
      - name: my-app-dlq
        visibility_timeout: 60
      - name: my-app-orders.fifo
        fifo: true
  iam:
    users:
      - user_name: developer
        create_access_key: true
      - user_name: readonly-user
    roles:
      - role_name: lambda-execution-role
        description: Role for Lambda function execution
        assume_role_policy: '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}'

默认初始资源（自动创建）：S3存储桶

emulate-default

、SQS队列

emulate-default-queue

、带有访问密钥对的IAM用户

admin

（密钥对：

AKIAIOSFODNN7EXAMPLE

/

wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

）。

API Endpoints

API端点

S3

S3 routes use root paths matching the real AWS S3 wire format. Legacy

/s3/

prefixed paths are also supported.

bash

undefined

S3路由使用与真实AWS S3协议格式匹配的根路径。同时支持传统的

/s3/

前缀路径。

bash

undefined

List all buckets

列出所有存储桶

curl http://localhost:4006/
-H "Authorization: Bearer $TOKEN"

Create bucket

创建存储桶

curl -X PUT http://localhost:4006/my-bucket
-H "Authorization: Bearer $TOKEN"

Delete bucket (must be empty)

删除存储桶（必须为空）

curl -X DELETE http://localhost:4006/my-bucket
-H "Authorization: Bearer $TOKEN"

Head bucket (check existence, get region)

查询存储桶（检查存在性、获取区域）

curl -I http://localhost:4006/my-bucket
-H "Authorization: Bearer $TOKEN"

List objects (with prefix, delimiter, pagination)

列出对象（支持前缀、分隔符、分页）

curl "http://localhost:4006/my-bucket?prefix=uploads/&delimiter=/&max-keys=100"
-H "Authorization: Bearer $TOKEN"

Put object

上传对象

curl -X PUT http://localhost:4006/my-bucket/path/to/file.txt
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: text/plain"
-H "x-amz-meta-author: test"
--data-binary "file contents"

Get object

下载对象

curl http://localhost:4006/my-bucket/path/to/file.txt
-H "Authorization: Bearer $TOKEN"

Head object (metadata only)

查询对象元数据

curl -I http://localhost:4006/my-bucket/path/to/file.txt
-H "Authorization: Bearer $TOKEN"

Delete object

删除对象

curl -X DELETE http://localhost:4006/my-bucket/path/to/file.txt
-H "Authorization: Bearer $TOKEN"

Copy object

复制对象

curl -X PUT http://localhost:4006/dest-bucket/copy.txt
-H "Authorization: Bearer $TOKEN"
-H "x-amz-copy-source: /source-bucket/original.txt"

undefined

curl -X PUT http://localhost:4006/dest-bucket/copy.txt
-H "Authorization: Bearer $TOKEN"
-H "x-amz-copy-source: /source-bucket/original.txt"

undefined

SQS

All SQS operations use

POST /sqs/

with

Action

as a form-urlencoded parameter.

bash

undefined

所有SQS操作均使用

POST /sqs/

，并将

Action

作为表单编码参数传递。

bash

undefined

Create queue

创建队列

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/x-www-form-urlencoded"
-d "Action=CreateQueue&QueueName=my-queue"

Create queue with attributes

创建带属性的队列

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/x-www-form-urlencoded"
-d "Action=CreateQueue&QueueName=my-queue&Attribute.1.Name=VisibilityTimeout&Attribute.1.Value=30"

List queues

列出队列

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=ListQueues"

List queues with prefix filter

按前缀过滤列出队列

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=ListQueues&QueueNamePrefix=my-"

Get queue URL

获取队列URL

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=GetQueueUrl&QueueName=my-queue"

Get queue attributes

获取队列属性

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=GetQueueAttributes&QueueUrl=<queue_url>"

Send message

发送消息

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=SendMessage&QueueUrl=<queue_url>&MessageBody=Hello+World"

Send message with attributes

发送带属性的消息

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=SendMessage&QueueUrl=<queue_url>&MessageBody=Hello&MessageAttribute.1.Name=type&MessageAttribute.1.Value.DataType=String&MessageAttribute.1.Value.StringValue=greeting"

Receive messages

接收消息

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=ReceiveMessage&QueueUrl=<queue_url>&MaxNumberOfMessages=5"

Delete message

删除消息

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=DeleteMessage&QueueUrl=<queue_url>&ReceiptHandle=<receipt_handle>"

Purge queue

清空队列

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=PurgeQueue&QueueUrl=<queue_url>"

Delete queue

删除队列

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=DeleteQueue&QueueUrl=<queue_url>"

undefined

curl -X POST http://localhost:4006/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=DeleteQueue&QueueUrl=<queue_url>"

undefined

IAM

All IAM operations use

POST /iam/

with

Action

as a form-urlencoded parameter.

bash

undefined

所有IAM操作均使用

POST /iam/

，并将

Action

作为表单编码参数传递。

bash

undefined

Create user

创建用户

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=CreateUser&UserName=new-user"

Get user

获取用户信息

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=GetUser&UserName=new-user"

List users

列出用户

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=ListUsers"

Delete user

删除用户

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=DeleteUser&UserName=new-user"

Create access key

创建访问密钥

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=CreateAccessKey&UserName=developer"

List access keys

列出访问密钥

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=ListAccessKeys&UserName=developer"

Delete access key

删除访问密钥

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=DeleteAccessKey&UserName=developer&AccessKeyId=AKIA..."

Create role

创建角色

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=CreateRole&RoleName=my-role&AssumeRolePolicyDocument={}"

Get role

获取角色信息

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=GetRole&RoleName=my-role"

List roles

列出角色

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=ListRoles"

Delete role

删除角色

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=DeleteRole&RoleName=my-role"

undefined

curl -X POST http://localhost:4006/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=DeleteRole&RoleName=my-role"

undefined

STS

All STS operations use

POST /sts/

with

Action

as a form-urlencoded parameter.

bash

undefined

所有STS操作均使用

POST /sts/

，并将

Action

作为表单编码参数传递。

bash

undefined

Get caller identity

获取调用者身份

curl -X POST http://localhost:4006/sts/
-H "Authorization: Bearer $TOKEN"
-d "Action=GetCallerIdentity"

Assume role

角色假设

curl -X POST http://localhost:4006/sts/
-H "Authorization: Bearer $TOKEN"
-d "Action=AssumeRole&RoleArn=arn:aws:iam::123456789012:role/my-role&RoleSessionName=my-session"

undefined

curl -X POST http://localhost:4006/sts/
-H "Authorization: Bearer $TOKEN"
-d "Action=AssumeRole&RoleArn=arn:aws:iam::123456789012:role/my-role&RoleSessionName=my-session"

undefined

Inspector

检查器

bash

undefined

bash

undefined

HTML dashboard (shows S3, SQS, IAM state)

HTML仪表板（显示S3、SQS、IAM状态）

curl http://localhost:4006/_inspector?tab=s3 curl http://localhost:4006/_inspector?tab=sqs curl http://localhost:4006/_inspector?tab=iam

undefined

curl http://localhost:4006/_inspector?tab=s3 curl http://localhost:4006/_inspector?tab=sqs curl http://localhost:4006/_inspector?tab=iam

undefined

Common Patterns

常见使用场景

Upload and Retrieve an Object

上传和获取对象

bash

TOKEN="test_token_admin"
BASE="http://localhost:4006"

bash

TOKEN="test_token_admin"
BASE="http://localhost:4006"

Create bucket

创建存储桶

curl -X PUT $BASE/my-data
-H "Authorization: Bearer $TOKEN"

Upload file

上传文件

curl -X PUT $BASE/my-data/config.json
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
--data-binary '{"key": "value"}'

Download file

下载文件

curl $BASE/my-data/config.json
-H "Authorization: Bearer $TOKEN"

undefined

curl $BASE/my-data/config.json
-H "Authorization: Bearer $TOKEN"

undefined

Send and Receive SQS Messages

发送和接收SQS消息

bash

TOKEN="test_token_admin"
BASE="http://localhost:4006"

bash

TOKEN="test_token_admin"
BASE="http://localhost:4006"

Get queue URL

获取队列URL

QUEUE_URL=$(curl -s -X POST $BASE/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=GetQueueUrl&QueueName=emulate-default-queue" | grep -oP '<QueueUrl>\K[^<]+')

Send message

发送消息

curl -X POST $BASE/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=SendMessage&QueueUrl=$QUEUE_URL&MessageBody=Hello+from+emulate"

Receive messages

接收消息

curl -X POST $BASE/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=ReceiveMessage&QueueUrl=$QUEUE_URL&MaxNumberOfMessages=1"

undefined

curl -X POST $BASE/sqs/
-H "Authorization: Bearer $TOKEN"
-d "Action=ReceiveMessage&QueueUrl=$QUEUE_URL&MaxNumberOfMessages=1"

undefined

Create IAM User with Access Key

创建带访问密钥的IAM用户

bash

TOKEN="test_token_admin"
BASE="http://localhost:4006"

bash

TOKEN="test_token_admin"
BASE="http://localhost:4006"

Create user

创建用户

curl -X POST $BASE/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=CreateUser&UserName=ci-user"

Generate access key

生成访问密钥

curl -X POST $BASE/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=CreateAccessKey&UserName=ci-user"

undefined

curl -X POST $BASE/iam/
-H "Authorization: Bearer $TOKEN"
-d "Action=CreateAccessKey&UserName=ci-user"

undefined

aws

Original

Translation

AWS Emulator

AWS 模拟器

Start

启动

AWS only

仅启动AWS模拟

Default port (when run alone)

默认端口（单独运行时）

http://localhost:4000

http://localhost:4000

Auth

认证

Pointing Your App at the Emulator

将应用指向模拟器

Environment Variable

环境变量

AWS SDK v3

AWS SDK v3

Seed Config

初始配置

API Endpoints

API端点

S3

S3

List all buckets

列出所有存储桶

Create bucket

创建存储桶

Delete bucket (must be empty)

删除存储桶（必须为空）

Head bucket (check existence, get region)

查询存储桶（检查存在性、获取区域）

List objects (with prefix, delimiter, pagination)

列出对象（支持前缀、分隔符、分页）

Put object

上传对象

Get object

下载对象

Head object (metadata only)

查询对象元数据

Delete object

删除对象

Copy object

复制对象

SQS

SQS

Create queue

创建队列

Create queue with attributes

创建带属性的队列

List queues

列出队列

List queues with prefix filter

按前缀过滤列出队列

Get queue URL

获取队列URL

Get queue attributes

获取队列属性

Send message

发送消息

Send message with attributes

发送带属性的消息

Receive messages

接收消息

Delete message

删除消息

Purge queue

清空队列

Delete queue

删除队列

IAM

IAM

Create user

创建用户

Get user

获取用户信息

List users