# @aws-blocks/blocks 中文文档

规范地址：https://npmcn.com/package/%40aws-blocks/blocks/

版本：0\.9\.0
npm 元数据更新时间：2026-11-02T10:26:33.699Z
中文译文更新时间：2026-11-07T13:28:27.071Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-blocks/blocks
原文对照：https://npmcn.com/package/%40aws-blocks/blocks/?lang=original
项目主页：https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/blocks#readme
源码仓库：https://github.com/aws-devtools-labs/aws-blocks

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.8 MB，218 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：26 个
- 首次发布：2026-06-15T23:39:48.099Z
- 最新版本发布：2026-11-02T10:26:33.298Z
- 近 30 天下载量：64228（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

**将后端和前端一起写出——完全打入,可运行在笔记本电脑上,可部署到AWS不变.**

## 安装

```sh
npm install @aws-blocks/blocks
```

也可以使用：`pnpm add @aws-blocks/blocks`、`yarn add @aws-blocks/blocks`、`bun add @aws-blocks/blocks`

## README

# AWS 块

**将后端和前端一起写出——完全打入,可运行在笔记本电脑上,可部署到AWS不变.**

AWS Blocks 是一个后端框架,由 **建筑块**:自装模块,每个模块捆绑一个 CCDK 构造,它的 AWS SDK 集成,和一个本地模拟. 您在一个目录中编译块,导出一个 API,然后用端到端的安全调用您的前端. 没有客户端生成,没有胶水代码,不需要启动AWS账户.

此套件 (`@aws-blocks/blocks`重新出口每个建筑块和核心原始物, 所以你从一个地方进口一切:

```typescript
import { Scope, ApiNamespace, KVStore, AuthBasic } from '@aws-blocks/blocks';
```

-   **类型安全, 结束到结束** ——前端直接调用后端方法;类型自动流出.
-   **当地第一** ——每个区块都作为模拟模型运行,所以你用零云设置来构建和测试.
-   **部署情况不变** —— 说 `npm run sandbox` 将模拟器换成真实的AWS服务(DynamoDB, Aurora, S3, Lambda...). 同样的代码.
-   **低仪式,高天花板** ——常见的东西是一行;当你需要基础的CDK构造或者AWS SDK时,它就在那里.

## 快速启动

```bash
npx @aws-blocks/create-blocks-app my-app
cd my-app
npm run dev          # → http://localhost:3000  (mocks, no AWS account needed)
```

`--template <name>` 选择启动器( e)`react`, (中文(简体) ), `nextjs`, (中文(简体) ), `backend`见 [`@aws-blocks/create-blocks-app`](https://www.npmjs.com/package/@aws-blocks/create-blocks-app)。 。 。 .

## 如何运作

你的整个后端 在一个目录中生活, `aws-blocks/`。您创建块,然后通过 `ApiNamespace`数字 :

```typescript
// aws-blocks/index.ts
import { Scope, ApiNamespace, KVStore } from '@aws-blocks/blocks';

const scope = new Scope('my-app');
const store = new KVStore(scope, 'cache');

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getValue(key: string) {
    return await store.get(key);
  },
  async setValue(key: string, value: string) {
    await store.put(key, value);
  },
}));
```

前端导入的 API 并称之为本地函数—— 完全输入, 不获取, 没有客户端代码 :

```typescript
// src/
import { api } from 'aws-blocks';

await api.setValue('greeting', 'hello');
const value = await api.getValue('greeting'); // typed: string | null
```

这就是整个模型: **定义块 = 导出 API = 在前端导入.** 运输(JSON-RPC) `/aws-blocks/api`)是为你处理的,是故意隐形的.

## 添加认证和数据

块作曲. 以下为认证后设置的相同API门并辅以可查询表格:

```typescript
// aws-blocks/index.ts
import { Scope, ApiNamespace, AuthBasic, DistributedTable } from '@aws-blocks/blocks';
import { z } from 'zod';

const scope = new Scope('my-app');

const auth = new AuthBasic(scope, 'auth', { passwordPolicy: { minLength: 8 } });

const notes = new DistributedTable(scope, 'notes', {
  schema: z.object({ userId: z.string(), noteId: z.string(), text: z.string() }),
  key: { partitionKey: 'userId', sortKey: 'noteId' },
});

// Sign-up / sign-in endpoints, ready to wire to the frontend
export const authApi = auth.createApi();

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async addNote(text: string) {
    const user = await auth.requireAuth(context);          // 401s if not signed in
    const noteId = crypto.randomUUID();
    await notes.put({ userId: user.username, noteId, text });
    return { noteId };
  },
  async listNotes() {
    const user = await auth.requireAuth(context);
    return await Array.fromAsync(notes.query({ where: { userId: { equals: user.username } } }));
  },
}));
```

> **警卫:** 每个 `ApiNamespace` 方法是一个公共互联网端点 **默认无效**通过调用打开一个方法 `auth.requireAuth(context)` (或 `auth.requireRole(...)`) 在顶上. 本地的嘲弄也无所作为——一种通俗的方法通过每一个本地的检查,仍然可以被任何人叫来的船只.

在前门, `@aws-blocks/blocks/ui` 给您一个提供者不可知的认证组件或驱动器 `authApi` 自己说:

```typescript
import { Authenticator, onAuthChange } from '@aws-blocks/blocks/ui';
import { authApi, api } from 'aws-blocks';

document.body.append(Authenticator(authApi));
onAuthChange(authApi, (user) => {
  if (user) api.listNotes().then(render);
});
```

## 建筑块

从需要开始:

-   **存储数据**
    -   简单密钥 = 值(笼盖、旗帜、用户预览) = `KVStore` (bb-kv-store) (英语)
    -   有索引和查询的有结构的记录 `DistributedTable` (bb-分布式表格) - **大多数数据的默认值**
    -   关系/SQL(合并、交易) 参见 [选择数据块](https://npmcn.com/package/%40aws-blocks/blocks/#readme-choosing-a-data-block) 下级
    -   文件、blobs、上传、静态资产 `FileBucket` (bb-file-bucket) (英语)
    -   单一配置值 `AppSetting` (bb-app-设定)
    -   高值证书( API 密钥、 OAuth 密钥、 连接字符串) ~ `Secret` (bb-secret),由AWS保密管理器支持
-   **认证用户**
    -   用户名/密码、原型/MVP `AuthBasic` (bb-auth-basic) (英语)
    -   认知用户库、外交部、团体 `AuthCognito` (bb-auth-cognitto) (英语)
    -   外部身份提供商(OIDC) `AuthOIDC` (bb-auth-oidc) (英语)
-   **在请求/答复之外运行工作**
    -   火灾和遗忘的背景工作 `AsyncJob` (bb -sync -job) (bb
    -   计划/经常性任务 `CronJob` (bb-cron-job) (英语)
-   **向浏览器提供实时更新** (聊天、在场、仪表板) `Realtime` (bb-实时)
-   **构建 AI 特性**
    -   使用工具的代理 + 对话 + `Agent` (bb-agent) (英语)
    -   语义文档检索(RAG) `KnowledgeBase` (bb-知识基础)
-   **发送交易邮件** → `EmailClient` (bb-电子邮件客户端)
-   **执行原始 HTTP 端点** (网页接收器、健康检查、重新定向、非JSON反应) —— `RawRoute` (核心);其他一切经历 `ApiNamespace` 难民保护委员会
-   **观察和操作**
    -   结构化日志 + `Logger` (bb-logger) (英语)
    -   自定义衡量标准 `Metrics` (bb-meters) (英语)
    -   分布的痕迹 `Tracer` (bb-tracer) (英语)
    -   自动云表仪表板 `Dashboard` (bb-dashboard) (英语)

### 选择数据块

默认为 `DistributedTable` 用于您的数据模型,除非您的域特别需要 SQL 引擎能力.

当您需要过滤或加入多个相关记录的结果,在多个维度上过滤没有预设分级的模型,存储大对象,需要交易,或者需要NoSQL不提供的SQL的灵活性或熟悉度时,可以到达其中一个SQL块.

如果您需要 SQL , 请选择 `DistributedDatabase` aurora DSQL,即PostgreSQL线-protocol兼容;参见 [Aurora DSQL SQL 兼容文档](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility.html) 用于支持的 SQL 特性。 使用 `Database` 特别是当你需要一个完整的(更昂贵) 具有行级安全,触发,程序,或PL/pgSQL功能的后置执行;大交易(超过3000行);或与已存在的Postgres数据库相整合. 注意它携带了至少0.5ACU的闲置成本,或者在从零缩放时冷却起步,这与其他两个区块不同.

## 建筑群文件

每一个建筑区都向内运送文件 `@aws-blocks/blocks` 软件包下 `docs/<block>/`: 每个 `docs/<block>/` 文件夹包含该块 `README.md`附加时 `API.md`, (中文(简体) ), `DESIGN.md`,以及 `CHANGELOG.md` 这里 要读取它们, 请找到捆绑的文件夹 :

```bash
node -p "require('path').dirname(require.resolve('@aws-blocks/blocks/docs/README.md'))"
```

如果解析失败, 则返回到 `node_modules/@aws-blocks/blocks/docs`。该文件夹持有本指南(`README.md`),框架本身 `API.md`, (中文(简体) ), `TROUBLESHOOTING.md`,以及 `CHANGELOG.md` (版本历史——在排除出故障时读取),每个块外加一个子文件夹;下面的目录列出每个块.

| 块 | 它会做什么 | 关键词 |
| --- | --- | --- |
| 认证通用 | AWS Blocks Auth Building Blocks的所有共享接口和UI组件. | —— 说 |
| bb - 代理服务器 | AI代理 与流,工具调用, 和对话的持续. | —— 说 |
| bb-应用程序设置 | 由SSM参数存储器支持的单一应用程序配置值. | —— 说 |
| bb-同步工作 | 背景工作处理由SQS支持,运行在Lambda或一个容器上. | 队列、 任务、 背景、 同步、 工人、 提交、 批量、 重试、 状态、 过渡、 SQS |
| 基础 | 使用 JWT 会话的简单用户名/密码认证,密码政策,以及可选代码确认的签名和密码重置. | —— 说 |
| bb - 自动识别 | 由Amazon Cognito用户池支持的认证. | —— 说 |
| bb-auth-oidc 图像 | AWS Blocks应用程序的OIDC登录入门. | —— 说 |
| bb - 计算 | 这个 `Compute` Building Block是选择工作量运行地点的单一地表. | —— 说 |
| bb-cron-job (英语) | 计划任务执行由 EventBridge 调度器和 Lambda 支持. | cron, 调度, 计时器, 周期性, 重复性, 速率, 事件桥, 背景, 间隔 |
| bb-dashboard 键盘 | 自动生成 Cloud Watch Dashboard 用于应用可观察性. | —— 说 |
| bb-数据 | 完整的 PostgreSQL 数据库——默认情况下提供 Aurora Serverles v2,或连接到现有的 PostgreSQL 数据库(Supabase, Neon等) 通过 `fromExisting()`。 。 。 . | —— 说 |
| bb-分布数据 | 无服务器SQL数据库由亚马逊·奥罗拉DSQL支持. | —— 说 |
| bb-分布式表格 | 结构化数据存储由DynamoDB支持,具有二级索引和丰富的查询能力. | —— 说 |
| bb-电子邮件客户端 | 通过Amazon SES发送交易邮件. | —— 说 |
| bb-文件夹 | 由Amazon S3支持的文件存储. | —— 说 |
| bb-知识库 | 语义文档检索由亚马逊·贝德罗克知识库支持. | —— 说 |
| bb-kv 仓库 | 简单的密钥值存储由DynamotB支持. | —— 说 |
| bb - 拖放器 | 结构化记录,采用一致的JSON格式、日志级别和背景元数据. | —— 说 |
| bb 度量衡 | 自定义应用度量衡由Amazon Cloud Watch支持(通过嵌入量子格式). | —— 说 |
| bb-实时 | 由API Gateway WebSocket + DynamoDB支持的实时酒吧/子消息. | —— 说 |
| bb - 密语 | 由 AWS 保密管理器支持的单一应用程序秘密 . | —— 说 |
| bb-tracer (英语) | 由AWS X-Ray支持的分布式追踪. | —— 说 |
| 核心项目 | 与AWS Blocks一起构建全存储应用的核心原始. | —— 说 |
| 托管 | 用于在 AWS 上部署网络应用程序的低级 CDK L3 构造 | —— 说 |
| 管道 | CDK 管道基于 CI/CD 为 AWS Blocks 应用程序所构建. | —— 说 |
|  |  |  |

## 地方发展和部署

|  | `npm run dev` | `npm run sandbox` |
| --- | --- | --- |
| 块为 | 模拟游戏 | 真实的 AWS 服务 |
| AWS 账户 | 无需 | 所需经费 |
| 数据 | 坚持 `.bb-data/` (删除重置) | 生活在AWS系统 |
| 用于 | 快速迭代、测试 | 对照实际服务进行生产前验证 |

> **部署需要AWS证书.** `npm run dev` 完全本地化(无证书). `npm run sandbox` 财务报告和审定财务报表 `npm run deploy` 提供真实的AWS资源,因此首先配置证书——例如. `aws login` (AWS CLI 2.32.0或以后), `aws configure sso` + 键 `aws sso login`,或 `aws configure` (核查 `aws sts get-caller-identity`) (中文(简体) ). 如果证书缺失或过期,两个命令在合成之前都停止,并打印他们所使用的配置文件的签名或刷新命令。 使用 **最低特权** 证书范围为你们组群部署的服务——不广泛 `Administrator` 访问.

在他们部署之前, `npm run sandbox` 财务报告和审定财务报表 `npm run deploy` 打印部署目标:CDK所部署的(AWS配置文件、环境访问密钥或容器或网络身份证书)和所配置的区域。 和 CDK 一样, 环境访问密钥在之前被使用 `AWS_PROFILE` 除非 `cdk.json` 设置配置 。 持有有效证书后,还显示账户名称和AWS账户计划(免费或付费),如果这些证书允许的话 `account:GetAccountInformation` 财务报告和审定财务报表 `freetier:GetAccountPlanState`。否则它们会显示“无法使用”并继续使用;这些内容不会停止部署。 当您与 AWS 管理的新 AWS 注册体验角色( 路径上的角色) 签约时 `/managed/` 那个 `account-access.amazonaws.com` 可以假设, 检查 `iam:GetRole`),产出也链接到 `https://settings.aws.com/billing` 用于限制开支。 在 AWS 设置中,在查看或更改其支出限制之前,验证您打算管理的项目是否与 CLI 部署目标匹配 。 如果你签了 `aws login`,在您注册前将配置区域设置为您的项目所在区域(`aws configure set region <region> --profile <name>`),并运行 `aws login` 以后再换吧. `npm run sandbox:destroy` 财务报告和审定财务报表 `npm run destroy` 只打印部署目标.

有经过核实的证书, `npm run sandbox` (包括 `npm run sandbox:deploy`和 `npm run deploy` 并检查CDK是否已在该账户和地区被拖入: 他们读取了 SSM 参数 `/cdk-bootstrap/<qualifier>/version`,在限定词是 `@aws-cdk/core:bootstrapQualifier` 从 `cdk.json` 上下文,或 CDK 默认值。 当参数不存在时,它们在合成并打印拖动这个账户和区域的指令前就停止了, `npx cdk bootstrap aws://<account-id>/<region> --app=`从项目目录中运行; `--app=` 使CDK不首先合成应用程序. 每一个账户和地区都需进行布道,这就创造了 `CDKToolkit` CloudFormation 堆栈, 包括 CDK 配置的 IAM 角色, 因此命令永远不会为您拖入陷阱 。 读取的任何其他结果,如拒绝读取或超时,并不停止部署.

`npm run deploy` 全面部署生产; `npm run sandbox:deploy` 一次部署沙盒并退出(没有表,用于脚本和CI); `npm run sandbox:destroy` 泪下沙盒。 同一后端代码在所有三个中运行——块切换执行自动.

导入 `@aws-blocks/blocks` 通过其默认(节点)条目宣布默认计算(`LambdaCompute`因此,CLI报告它在遥测。 只有在远程测量读取注册簿时,在构建的应用程序的块后,才将其折叠起来 `LambdaCompute` 以优先为准。 这个 `cdk` 财务报告和审定财务报表 `browser` 条目不声明.

`npm run deploy` 流出云阵事件到 **静态** 他们发生的时候,所以 `npm run deploy | tee deploy.log` 显示实事求是的进步 而不是沉默几分钟, 部署失败保持其理由 **标准** (因为部署失败了) 在POSIX上,部署也能活过一个迷失的收获: `SIGTERM`,或任何 `SIGHUP` - 一个封闭的终端,一个背景 `npm run deploy &` ——记录一行并保持流线,而不是放弃堆栈更新 Cloud Formation 仍在应用. 按 Ctrl- C 键,或发送 `SIGTERM` 两次,停止它。 该信号恢复能力仅为 POSIX : Windows 没有进程组和 OS 交付 `SIGTERM`编号 :`SIGHUP`,所以在进程树上有一个杀 仍然结束部署.

## 测试

最快的循环是通过其输入的 API 调用 `test/e2e.test.ts` ——没有浏览器,没有嘲笑:

```typescript
import { test } from 'node:test';
import assert from 'node:assert';
import type { api as ApiType } from 'aws-blocks';

let api: typeof ApiType;
test.before(async () => { api = (await import('aws-blocks')).api; });

test('stores and reads back a value', async () => {
  await api.setValue('k', 'v');
  assert.equal(await api.getValue('k'), 'v');
});
```

运行 `npm run test:e2e`先写测试,然后对着嘲笑,直到它通过.

## 最佳做法

-   **导出每个 API** - 前端只能导入你的东西 `export` 从 `aws-blocks/index.ts`。 。 。 .
-   **以计划验证** 将 Zod/Valibot 计划传递到数据块进行编译时间 _财务报告和审定财务报表_ 运行时类型安全 .
-   **别挡住请求** ——使用 `AsyncJob` 为慢事; `submit()` 返回 a `jobId` 马上.
-   **警惕种族** - 使用有条件的写作(`ifNotExists`, (中文(简体) ), `ifValueEquals`, (中文(简体) ), `ifFieldEquals`)而不是读取-修改-写作.
-   **本地先测试** ——嘲弄行为像真正的服务;一旦绿色就部署.

## 常见错误

-   **未指定的终点** - 方法是公开的,除非你打电话 `requireAuth`编号 :`requireRole`本地的模拟器不会给你这个.
-   **忘记导出** - 一个 `ApiNamespace` 您不会被前端所忽略.
-   **`Database` 何时 `DistributedTable` 一定会** ——"奥罗拉"成本较高,且起步冷;"SQL"只有在需要时才能到达.
-   **校正 REST 风格路径** 没有 `GET /api/getData`所有电话都是JSON -RPC `POST`下级 `/aws-blocks/api`; 替换为输入.

## 安全考虑

-   使用 `await auth.requireAuth(context)` 在不应该公开的每一种方法中——ApiNamespace方法都是 **默认未校正**
-   使用 `new Secret(scope, id)` aPI 密钥和证书 `Secret` 被推荐为生产秘密之家. `new AppSetting(scope, id, { secret: true })` 是一个自由的,加密的倒置,只用于一个低值的秘密。 在源代码中不要硬化秘密值, 不要通过纯文本环境变量将真实的秘密传送给部署的应用程序—— 将它们传送到 `Secret`编号 :`AppSetting`
-   总是在 KVStore/ AppSetting 中附加一个接受用户数据的计划—— RPC 层验证结构而非业务逻辑
-   不添加宽度 `*` IAM政策——每个建筑区已经给予自身资源最少的优惠
-   永远不变 `blockPublicAccess` 在FileBucket上——通过 CloudFront 提供公共文件
-   配置 `defaults.allowedOrigins` 明确用于生产——避免通配符
-   `defaults.allowedOrigins` 仅覆盖 API —— 从浏览器获取其预先签名的 URL 或文件控件的 FileBucket `corsRules` 列出您的前端来源( 包括 `http://localhost:3000` 用于对沙盒的本地前端),或上传/下载失败,一旦部署 CORS 错误
-   跨域部署,通过 `crossDomain: true` 用于验证构造器(可转让设备) `SameSite=None; Secure; Partitioned`(中文(简体) )
-   启用 `frontDoor: { features: { monitoring: { enabled: true, subscriptions: [new subs.EmailSubscription('oncall@example.com')] } } }` 用于生产警报的东道主`subs` =: `aws-cdk-lib/aws-sns-subscriptions`; 仅电子邮件/URL; 顶级 `monitoring` 道具是被贬损的别名)
-   通过 CDK 添加 WPAF 和 API Gateway 节奏, 用于 公用软件 — 默认不包括
-   Logger提供串行安全(circular refs,类型强制),但不编辑敏感内容——从不向 Logger 方法传递原始证书,令牌或秘密;在记录前将上下文对象进行消毒

### IAM 硬化

每个区块计算为一个共享的IAM(身份和访问管理)执行角色运行,每个建筑区块都给予它权限. 设定 `defaults.permissionsBoundary` 将附件a [权限边界](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)对每个IAM角色 AWS Blocks 设定一个有效权限的上限。 传递政策名称,其完整的ARN(当政策有路径时需要),或 `iam.IManagedPolicy`。它在两个预设中都没有设置,而未设置的叶片模板没有改变.

```typescript
// aws-blocks/index.cdk.ts
export const blocksStack = await BlocksStack.create(app, stackName, {
  backendHandlerPath: join(__dirname, 'index.handler.ts'),
  backendCDKPath: join(__dirname, 'index.ts'),
  defaults: { ...BlocksPresets.production, permissionsBoundary: 'my-app-boundary' },
});
```

-   **报曰.** 无论有没有边界,每个合成人都会写出共同角色的构成政策 `cdk.out/<stack>.blocks-iam.json` (单位:千美元)`<stack>.<backendId>.blocks-iam.json` 用于嵌入式 `BlocksBackend`),它没有部署,所以CI可以通过它来捕捉许可增长.
-   **范围.** 在一个 `BlocksStack` 边框覆盖堆栈中的每个角色; 在嵌入式上 `BlocksBackend` 它覆盖了后端的子树外加堆栈级的CDK(Cloud Development Kit)单通角色 它的块加.
-   **CDK语境.** 如果是CDK的话 `@aws-cdk/core:permissionsBoundary` 设置上下文, `defaults.permissionsBoundary` blocks创造的角色获胜 合成警告.

细节,包括在许多应用程序中共享一个 AWS 账户,都在捆绑中 `@aws-blocks/core` 读取`docs/core/README.md`)),"IAM:允许边界和组成政策报告"和"在一个AWS账户(共享平台)中运行许多应用"等章节.

## VPC 支持

AWS Blocks 支持在 VPC 中运行您的后端,用于网络级别隔离或连接到 VPC 约束的资源. 您可以让 Blocks 自动管理端点提供和安全小组, 或者带来一个完全配置的 VPC 并处理自己的网络.

见 [瓦努阿图](https://npmcn.com/package/%40aws-blocks/blocks/VPC.md) 用于使用、配置选项、成本细节和关于何时适合VPC的指导.

## 参考文献

-   **每个街区的文件:** `docs/<block>/README.md` (概览),加 `docs/<block>/API.md` (完整的API参考)和 `docs/<block>/DESIGN.md` (architecture & programmation) 凡有——例如. `docs/bb-distributed-table/README.md`。目录 + 决策树 `docs/README.md`。 。 。 .
-   **UI 组件** (单位:千美元)`@aws-blocks/blocks/ui`: `Authenticator`, (中文(简体) ), `AuthenticatedContent`, (中文(简体) ), `AccountMenuBar`, (中文(简体) ), `onAuthChange`, (中文(简体) ), `broadcastAuthChange` ——框架不可知,回DOM节点. 见 `@aws-blocks/auth-common` 读取.
-   **安全部门改革** (单位:千美元)`@aws-blocks/blocks/server`: `withAuth` 在服务器渲染时将浏览器 cookie 转发到 API 调用 。 见 `@aws-blocks/core` 读取.
-   **电线协议调试( D) :** 客户端是JSON-RPC 2.0 `/aws-blocks/api` 你不应该直接打电话 对于 `curl`\- 一级故障,看 [难题. md](https://npmcn.com/package/%40aws-blocks/blocks/TROUBLESHOOTING.md)。 。 。 .

## 常见问题

### @aws-blocks/blocks 是什么？

将后端和前端一起写出——完全打入,可运行在笔记本电脑上,可部署到AWS不变\.

### 如何安装 @aws-blocks/blocks？

在项目目录运行 npm install @aws-blocks/blocks，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 blocks-vendorize、blocks-generate-client，可以用 npx blocks-vendorize 直接运行。

### @aws-blocks/blocks 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-blocks/blocks 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aws-blocks/blocks 可以商用吗？

@aws-blocks/blocks 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-blocks/blocks 的下载量有多少？

根据 npm 官方下载统计，@aws-blocks/blocks 在 2026/10/07 – 2026/11/05 这 30 天内被下载 64,228 次，日均约 2,141 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-blocks/blocks 还在维护吗？

最新版本 0\.9\.0 发布于 2026/11/02（5 天前）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/06/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。