# @algorandfoundation/algokit-client-generator 中文文档

规范地址：https://npmcn.com/package/%40algorandfoundation/algokit-client-generator/

版本：6\.0\.2
npm 元数据更新时间：2026-11-06T12:58:32.387Z
中文译文更新时间：2026-11-06T13:09:38.124Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40algorandfoundation/algokit-client-generator
原文对照：https://npmcn.com/package/%40algorandfoundation/algokit-client-generator/?lang=original
项目主页：https://github.com/algorandfoundation/algokit-ts#readme
源码仓库：https://github.com/algorandfoundation/algokit-ts

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

- 包体积（解压后）：533 kB，122 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0
- 运行依赖：4 个
- peer 依赖：algosdk ^3\.2\.0，@algorandfoundation/algokit-utils ^9\.0\.0
- 首次发布：2023-05-16T22:02:34.647Z
- 最新版本发布：2026-11-06T12:58:32.008Z
- 近 30 天下载量：4262（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：145（近 12 个月 19 个）

## 中文简介

生成一个TypeScript客户端,用于与Algorand Blockchain互动,并部署ARC-0032智能合同.

## 安装

```sh
npm install @algorandfoundation/algokit-client-generator
```

也可以使用：`pnpm add @algorandfoundation/algokit-client-generator`、`yarn add @algorandfoundation/algokit-client-generator`、`bun add @algorandfoundation/algokit-client-generator`

## README

# AlgoKit 类型Script 客户端生成器(algokit-client-generator-ts)

此工程在 TypeScript 为 Algorand Blockchain 生成一个类型安全的智能合同客户端,该客户端可以包装 [应用程序客户端](https://algorandfoundation.github.io/algokit-ts/utils/capabilities/app-client/) 内 [阿尔戈基特Utils](https://github.com/algorandfoundation/algokit-ts/tree/main/algokit-utils-ts) 并调整它在特定的智能合同。 它通过阅读一个 [ARC-56 (韩语)](https://github.com/algorandfoundation/ARCs/pull/258) 或者说 [ARC-32 (韩语)](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md) 应用程序 spec文件并生成一个客户端,该客户端会曝光目标智能合同中每个ABI方法的方法,同时帮助创建,更新并删除应用程序.

## 使用量

### 先决条件

为了能够消耗生成的文件, 您需要将其包含在 TypeScript 工程中, 该工程( 至少) 安装了以下软件包 :

```
npm install @algorandfoundation/algokit-utils@^9.0.0
```

注:生成器第6版需要 `@algorandfoundation/algokit-utils@^9.0.0` (与 algosdk v3; 它与从 algosdk 解开的 AlgoKit Utils v10不相容.

### 移徙

如果您正在将您的项目从一个旧生成的打字客户端迁移到 v4 , 请参考 [v4 迁移指南](https://github.com/algorandfoundation/algokit-ts/blob/main/algokit-client-generator-ts/docs/v4-migration.md)。 。 。 .

### 使用

Cli可以通过以下命令生成客户端.

```bash
npx --yes  @algorandfoundation/algokit-client-generator generate -a ./application.json -o ./client.generated.ts
```

#### CLI 选项

CLI支持以下选项:

-   `-a, --application <path>` (需要):指定ARC-56或ARC-32应用程序的路径. json 文件
-   `-o, --output <path>` (需要):指定生成类型脚本客户端的输出文件路径
-   `--pn, --preserve-names`: 保存应用程序中的名称. json spec 而不是将其消毒到骆驼Case
-   `-m, --mode <mode>`: 在指定模式生成客户端( 默认 ): `full`(中文(简体) )
    -   `full`: 生成具有工厂、部署能力和所有特性的完整客户端
    -   `minimal`:生成一个没有工厂或部署能力的轻量级客户端,导致产出更小

#### CLI 实例

生成完整的客户端( 默认 ) :

```bash
npx --yes @algorandfoundation/algokit-client-generator generate -a ./application.json -o ./client.ts
```

生成一个最小客户端 :

```bash
npx --yes @algorandfoundation/algokit-client-generator generate -a ./application.json -o ./client.ts -m minimal
```

#### 生成模式

生成器支持两种模式:

**全模式( 默认) :**

-   包括制造和部署智能合同的工厂类别
-   包括部署类型和方法
-   包括与部署有关的所有元数据(源代码、字节代码、模板变量)
-   包括与已部署合同互动的客户类别
-   最适合开发、部署和互动工作流程,或产出规模不那么重要的地方

**最小模式 :**

-   不包括工厂类别和部署能力
-   不包括减少产出规模的与部署有关的元数据
-   仅包括与已部署合同互动的客户类别
-   仅需要与现有合同互动的假设情况最好

#### 程序化 API

或者,可以通过引用代码生成客户端 `generate` 函数配对 `writeDocumentPartsToString` 或者说 `writeDocumentPartsToStream` 取决于你的需求。 我们也让帮助者可以任意加载并验证一个应用程序.json文件.

```ts
import fs from 'fs'
import {
  writeDocumentPartsToStream,
  writeDocumentPartsToString,
  generate,
  loadApplicationJson,
  validateApplicationJson,
} from '@algorandfoundation/algokit-client-generator'
import appJson from './application.json'

const appJsonFromFile = loadApplicationJson('./application.json')
const appJsonFromObject = validateApplicationJson(appJson)

const fileStream = fs.createWriteStream('./client.ts', {
  flags: 'w',
})
writeDocumentPartsToStream(generate(appJsonFromFile), fileStream)

// Generate a full client (default)
const clientAsString = writeDocumentPartsToString(generate(appJsonFromObject))

// Generate a minimal client
const minimalClientAsString = writeDocumentPartsToString(generate(appJsonFromObject, { mode: 'minimal' }))
```

关于如何使用生成的客户端的详情,请参见更详细的 [使用文档](https://github.com/algorandfoundation/algokit-ts/blob/main/algokit-client-generator-ts/docs/usage.md)

## 代码示例

有范围 [实例](https://github.com/algorandfoundation/algokit-ts/blob/main/algokit-client-generator-ts/examples) 可以查看源智能合同(例如:. `{contract.py}`),生成客户端(`client.ts`)和一些显示如何使用客户端的测试(`client.spec.ts`) (中文(简体) ).

## 捐款

如果您想为该项目做出贡献,以下信息将有所帮助.

### 初始设置

1.  克隆此本地寄存器
    
2.  安装先决条件 :
    
    -   安装 `AlgoKit` - 说吧 [链接](https://github.com/algorandfoundation/algokit-cli#install): 确保您能够执行 `algokit --version`。 。 。 .
    -   启动本地环境; 运行 `algokit bootstrap all` 在此文件夹中,它将:
        -   安装 `Poetry` - 说吧 [链接](https://python-poetry.org/docs/#installation): 最低要求的版本为: `1.2`。确保您能够执行 `poetry -V` 获得 `1.2`\+ 键
        -   运行 `poetry install` 在根目录中,将设置 `.venv` 有 Python 虚拟环境的文件夹, 并安装所有 Python 依赖性
        -   运行 `pnpm install`
3.  打开工程并开始调试 / 通过 :
    
    -   VS 代码
        1.  在 VS 代码中打开寄存器根
        2.  安装推荐的扩展
        3.  通过测试探索器运行测试
    -   EIDO( 如 PyCharm) : 化学反应
        1.  在 IDE 中打开寄存器根
        2.  它应该自动检测它是一个"诗"项目,并设置了Python解释器和虚拟环境.
        3.  运行测试
    -   其它
        1.  在您选择的文本编辑器中打开寄存器根
        2.  运行 `pnpm run test`

### 随后

1.  如果您更新了最新的源代码, 并且您需要运行新的依赖性 `algokit bootstrap all` 再来一次
2.  遵循上文第3步

### 树立榜样

在那个 `examples` 文件夹中有一系列实例合同及其生成的客户端。 这些合同是使用下列方法建造的: [阿尔高朗活字](https://github.com/algorandfoundation/puya)。 。 。 .

如果您想要修改任何智能合同实例, 并重新生成 ARC- 0032 应用程序。 然后更改相应的文件 `examples/{contract}/{contract}.py` 文件然后运行 :

```
poetry run python -m examples
```

或者在Visual Studio代码中,您可以使用默认的构建任务(Ctrl+Shift+B).

重新生成运行的生成客户端 `pnpm run update-approvals`。 。 。 .

### 持续整合/持续部署(CI/CD)

这个项目使用 [GitHub 动作](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions) 以定义 CI/CD 工作流程,这些工作流程位于 [`.github/workflows`](https://github.com/algorandfoundation/algokit-ts/blob/main/algokit-client-generator-ts/.github/workflows) 文件夹.

### 核准测试

对生成的代码作任何修改将会导致批准测试失败. 通过生成客户端版本进行审批测试 并输出到 `./examples/APP_NAME/client.generated.ts` 然后与核准的版本比较 `./examples/APP_NAME/client.ts`。如果 更改并打破批准测试, 您需要更新批准版本, 用生成的版本覆盖它 . 你们可以跑 `pnpm run update-approvals` 一次更新所有核准客户.

## 常见问题

### @algorandfoundation/algokit-client-generator 是什么？

生成一个TypeScript客户端,用于与Algorand Blockchain互动,并部署ARC-0032智能合同\.

### 如何安装 @algorandfoundation/algokit-client-generator？

在项目目录运行 npm install @algorandfoundation/algokit-client-generator，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：algosdk（^3\.2\.0）、@algorandfoundation/algokit-utils（^9\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 algokitgen、algokit-client-generator，可以用 npx algokitgen 直接运行。

### @algorandfoundation/algokit-client-generator 支持 TypeScript 吗？

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

### @algorandfoundation/algokit-client-generator 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @algorandfoundation/algokit-client-generator 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @algorandfoundation/algokit-client-generator 可以商用吗？

@algorandfoundation/algokit-client-generator 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @algorandfoundation/algokit-client-generator 的下载量有多少？

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

### @algorandfoundation/algokit-client-generator 还在维护吗？

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