# @azure-tools/typespec-client-generator-cli 中文文档

规范地址：https://npmcn.com/package/%40azure-tools/typespec-client-generator-cli/

版本：0\.33\.1
npm 元数据更新时间：2026-05-01T18:34:47.782Z
中文译文更新时间：2026-11-07T13:51:07.217Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40azure-tools/typespec-client-generator-cli
原文对照：https://npmcn.com/package/%40azure-tools/typespec-client-generator-cli/?lang=original
项目主页：https://github.com/Azure/azure-sdk-tools/tree/main/tools/tsp-client#readme
源码仓库：https://github.com/Azure/azure-sdk-tools

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

- 包体积（解压后）：149 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.19\.0
- 运行依赖：11 个
- peer 依赖：@typespec/compiler 1\.0\.0-rc\.1 \|\| \>=1\.0\.0 \<2\.0\.0
- 首次发布：2023-10-20T23:42:06.510Z
- 最新版本发布：2026-05-01T18:34:47.645Z
- 近 30 天下载量：51880（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 5 个）

## 中文简介

从 TypeSpec 生成 Azure SDK 的工具

## 安装

```sh
npm install @azure-tools/typespec-client-generator-cli
```

也可以使用：`pnpm add @azure-tools/typespec-client-generator-cli`、`yarn add @azure-tools/typespec-client-generator-cli`、`bun add @azure-tools/typespec-client-generator-cli`

## README

# tsp 客户端

`tsp-client` 是一个简单的命令行工具来方便从 TypeSpec 生成客户端库.

## 先决条件

-   [节点js 18.19 LTS](https://nodejs.org/en/download/) 或需要较晚时间

## 安装

```bash
npm install -g @azure-tools/typespec-client-generator-cli
```

> 注: " Repo " 所有人应当遵守《公约》的步骤 [tsp - 客户端重传设置](https://npmcn.com/package/%40azure-tools/typespec-client-generator-cli/repo_setup.md) 医生.

## 使用量

```bash
tsp-client < command > [options]
```

## 图标

使用其中一个支持的命令从TypeSpec项目开始生成客户端.

此工具将默认使用您当前的工作目录生成客户端 用于查找相关的配置文件。 要指定不同的输出目录, 请使用 页:1 `-o` 或者说 `--output-dir` 选项.

要查看支持的命令, 请运行 :

```bash
tsp-client --help
```

要查看支持的特定命令的参数和选项, 运行:

```bash
tsp-client < command > --help
```

使用 `init` 命令 :

```bash
tsp-client init --help
```

### 输入

使用 tspconfig.yaml 初始化客户端库目录 。 当运行此命令时, 在本地路径或远程 tspconfig 的 URL 中通过 。 来啊 `-c` 或者说 `--tsp-config` 旗帜。 如果远程, tspconfig 。 Yaml必须包含路径中的具体承诺. (见下文实例)

这个 `init` 命令按照整个Azure SDK语言寄存器所用的标准模式生成目录结构,创建 [tsp-location.yaml (中文(简体) )](https://npmcn.com/package/%40azure-tools/typespec-client-generator-cli/#readme-tsp-locationyaml) 文件用于控制生成,并履行客户端库的初始生成。 如果您想要跳过客户端库生成, 请通过 `--skip-sync-and-generate` 旗帜.

> 重要: 此命令应从寄存器的根来运行 。 示例寄存器根 : `azure-sdk-for-python/`

示例

```bash
tsp-client init -c https://github.com/Azure/azure-rest-api-specs/blob/dee71463cbde1d416c47cf544e34f7966a94ddcb/specification/contosowidgetmanager/Contoso.WidgetManager/tspconfig.yaml
```

### 更新

这个 `update` 命令将查找一个 [tsp-location.yaml (中文(简体) )](https://npmcn.com/package/%40azure-tools/typespec-client-generator-cli/#readme-tsp-locationyaml) 当前目录中的文件可以同步 TypeSpec 项目并生成客户端库。 更新流称为 `sync` 财务报告和审定财务报表 `generate` 命令,所以如果需要将这些步骤分开,请使用 `sync` 财务报告和审定财务报表 `generate` 相反,命令是分开的.

示例

```bash
tsp-client update
```

批量图书馆的生成参见 [批量库生成](https://npmcn.com/package/%40azure-tools/typespec-client-generator-cli/#readme-batch-library-generation) 说明.

### 同步

用 tsp-location.yaml 中指定的参数同步 TypeSpec 项目.

默认情况下 `sync` 命令将查找 tsp- 位置。 获取项目细节并同步到一个名为“ 临时目录” 的临时目录 `TempTypeSpecFiles`。作为替代,您可以在 `--local-spec-repo` 标记与您本地 TypeSpec 项目的路径, 将这些文件拖入您的临时目录 .

示例

```bash
tsp-client sync
```

### 生成

从 TypeSpec 项目创建客户端库. 这个 `generate` 命令应在 `sync` 命令. `generate` 取决于存在 `TempTypeSpecFiles` 创建目录 `sync` 命令和命令时 `emitter-package.json` 文件在以下路径中检查到您的仓库 : `<repo root>/eng/emitter-package.json`编辑 `emitter-package.json` 文件用于安装项目依赖性并获得适当的发射包.

示例

```bash
tsp-client generate
```

### 转换

将已有的 swagger 规格转换为 TypeSpec 项目 。 此命令只应运行一次才能开始在 TypeSpec 项目上工作. TypeSpec项目需要在转换后手动优化并进行全面审查. 当使用此命令时, 需要通过 : `--swagger-readme` 旗帜。 默认情况下,被转换的TypeSpec项目将用标准模式和模板来利用TypeSpec内置库(高推荐),这将造成生成的TypeSpec和原生的 swagger之间的差异. 如果你真的不想要这个 想要的差异,添加 `--fully-compatible` 旗来生成一个完全兼容 swagger 的 Typec 项目.

示例

```bash
tsp-client convert -o ./Contoso.WidgetManager --swagger-readme < path-to > /readme.md
```

### 排序拓扑器

用 TypeSpec 生成的 swagger 排序现有的 swagger 规格为相同的内容顺序 。 这将允许您比较并识别当前所生成的 swagger 和 TypeSpec 之间的区别 。 在创建已转换的 TypeSpec PR 之前, 您应该运行此命令 .

### 生成配置文件

此命令生成 tsp- 客户端使用的默认配置文件 。 运行此命令以生成 `emitter-package.json` 财务报告和审定财务报表 `emitter-package-lock.json` 下划线 **纳克/** 您当前仓库的目录 .

**要求: 使用 `--package-json` 标记以指定软件包的路径。json文件用于生成客户端库.**

示例

```bash
tsp-client generate-config-files --package-json < path-to-emitter-repo-clone > /package.json
```

任何额外的 npm 旗可以使用 `--npm-args` 选项。 这允许您通过任何 npm 旗帜, 如 `--registry`, (中文(简体) ), `--legacy-peer-deps`, (中文(简体) ), `--force`空格分隔字符串中的等:

```bash
tsp-client generate-config-files --package-json < path-to-emitter-repo-clone > /package.json --npm-args="--registry=https://my-registry --legacy-peer-deps"
```

使用 `azure-sdk-for-js` 编辑 `@azure-tools/typespec-ts` 发射器 :

这个 `--package-json` 旗帜应该是重新复制@azure-tools/typespec-ts包的相对或绝对路径.

```bash
azure-sdk-for-js > tsp-client generate-config-files --package-json < path-to-emitter-repo-clone > /package.json
```

要明确指定您想要绑定的依赖性, 请在软件包中添加一个新字段。 json 文件名为 `"azure-sdk/emitter-package-json-pinning"` 带有您想要转发到排放包的依赖性列表 。 这些依赖关系必须在您的软件包中指定 。 json的devDependency,以便工具指定正确的版本.

> 注:如果 `azure-sdk/emitter-package-json-pinning` 字段从 package.json 文件中缺失。该工具将默认对下面列出的软件包进行针入 `peerDependencies`。 。 。 .

示例包.json 使用 `"azure-sdk/emitter-package-json-pinning"`数字 :

```json
{
  "name": "@azure-tools/typespec-foo",
  "version": "0.4.0-alpha.20250110.1",
  ...
  "dependencies": {
    "@azure-tools/generator-foo": "0.3.0",
    "@typespec/http-client-foo": "1.2.0"
  },
  "devDependencies": {
    "@typespec/compiler": "0.64.0",
    "rimraf": "^6.0",
  },
  "azure-sdk/emitter-package-json-pinning": [
    "@typespec/compiler"
  ]
}
```

示例 `emitter-package.json` 由软件包生成. json 上所示:

```json
{
  "main": "dist/src/index.js",
  "dependencies": {
    "@azure-tools/typespec-foo": "0.4.0-alpha.20250110.1"
  },
  "devDependencies": {
    "@typespec/compiler": "0.64.0"
  }
}
```

如果您需要覆盖您的 emiters- package.json 的依赖性, 您可以创建 json 文件, 以明确列出您想要覆盖的软件包和相应的版本 。 这将增加一个 `overrides` 在您发射包中的区域。 json 将用于 `npm install` 或者说 `npm ci`。 。 。 . [参见 npm 覆盖 doc .](https://docs.npmjs.com/cli/v10/configuring-npm/package-json?v=true#overrides)

有包覆盖的示例 json 文件 :

```json
{
  "@azure-tools/typespec-foo": "https://<dev-feed-url>/typespec-foo-0.4.0-alpha.20250110.1.tgz",
  "@azure-tools/generator-foo": "https://<dev-feed-url>/generator-foo-1.3.0-alpha.20250110.1.tgz"
}
```

指定覆盖的示例命令 :

```bash
tsp-client generate-config-files --overrides my_overrides.json --package-json < path-to-emitter-repo-clone > /package.json
```

示例 `emitter-package.json` 使用覆盖生成 :

```json
{
  "main": "dist/src/index.js",
  "dependencies": {
    "@azure-tools/typespec-foo": "https://<dev-feed-url>/typespec-foo-0.4.0-alpha.20250110.1.tgz"
  },
  "devDependencies": {
    "@typespec/compiler": "~0.64.0"
  },
  "overrides": {
    "@azure-tools/generator-foo": "https://<dev-feed-url>/generator-foo-1.3.0-alpha.20250110.1.tgz"
  }
}
```

### 生成锁定文件

根据已有的 eng/ 目录在 eng/ 目录下生成一个发报- package-lock.json `<repo-root>/eng/emitter-package.json`。 。 。 .

示例

```bash
tsp-client generate-lock-file
```

任何额外的 npm 旗帜都可以传送到下面 `npm install` 使用 `--npm-args` 选项。 这允许您通过任何 npm 旗帜, 如 `--registry`, (中文(简体) ), `--legacy-peer-deps`, (中文(简体) ), `--force`空格分隔字符串中的等:

```bash
tsp-client generate-lock-file --npm-args="--registry=https://my-registry --legacy-peer-deps"
```

### 安装依赖性

默认情况下在寄存器的根部安装嵌入于emitter-package.json和emitter-package-lock.json(如果存在的话)的依赖性. 该命令支持一个位置路径参数,如果需要将依赖性安装到另一个目录中.

> IMPORANT:节点 模块/目录需要安装在一条路径上,基本npm命令可以使用. 通常与要编译的目标 Typec 项目在同一目录路径内.

```bash
tsp-client install-dependencies [optional install path]
```

## 重要概念

### 每个项目设置

每个工程都需要有一个名为tsp-location的配置文件. 将告诉工具在哪里找到 TypeSpec 项目 .

#### tsp-location.yaml (中文(简体) )

此文件通过 `tsp-client init` 命令或您可以在项目目录下手动创建它,以运行此工具所支持的其他命令.

> 注: 此文件应存在于每个服务的项目目录下.

文件有以下属性:

| 财产 | 说明 | 必需 |
| --- | --- | --- |
| 目录 | 用于服务的主.tsp所居住的顶级目录. 这应该是相对于 spec repo 根, 如 `specification/cognitiveservices/OpenAI.Inference` | 真实 |
| 额外 目录 | 有时一个类型文件会使用可能不在主目录下的相对导入. 在这种情况下,一个 `directory` 将不足以删除所有必要的文件。 要支持此选项, 您可以指定额外的目录为要同步的列表, 以便同步所有需要的文件 . | 假: 默认 = 无效 |
| 承诺 | 您想要生成的类型文件版本的承诺 sha 。 这使得我们能够在一代人身上拥有一能,直到我们选择指向后来的版本. | 真实 |
| 还原 | 重播的这个谱系存在。 这应该是 `Azure/azure-rest-api-specs` 或者说 `Azure/azure-rest-api-specs-pr`。请注意, pr 将在本地工作, 但不会在 CI 中工作, 除非我们添加另一个更改来处理基于符号的认证 . | 真实 |
| 输入点文件 | 用于编译 TypeSpec 项目的特定入口文件 。 注:此选项只应使用非标准条目文件名。 不使用此选项, 并带有标准切入点 : `client.tsp` 或者说 `main.tsp`。 。 。 . | 虚假 |

示例

```yml
directory: specification/contosowidgetmanager/Contoso.WidgetManager
commit: 431eb865a581da2cd7b9e953ae52cb146f31c2a6
repo: Azure/azure-rest-api-specs
additionalDirectories:
  - specification/contosowidgetmanager/Contoso.WidgetManager.Shared/
```

## 高级设想

### 批量库生成

批量客户端库生成仅支持 `tsp-client update` 命令。 为了使批量生成能够遵循这些步骤:

1.  增加tsp-位置. 将生成所有批次库的父目录中的 yaml 文件 。 示例

```
- sdk/
  - foo/
    - tsp-location.yaml
    - bar/
    - zas/
```

2.  顶级tsp-位置. 雅姆尔应该只有 `batch` 属性配置。 分批地产预计将是直接包含正则 tsp-位置的子目录. 为客户端库生成配备了适当配置的yaml文件. 其他 tsp- location.yaml 属性, 如 `directory`, (中文(简体) ), `commit`, (中文(简体) ), `repo`, (中文(简体) ), `additionalDirectories` 目前不支持 `batch` 配置 。 示例

```yml
batch:
  - ./bar
  - ./zas
```

3.  确保在 `batch` 列表有 tsp- 位置。 为它们配置了 yaml 文件 。 若分行所出无有取取取取取取取出. Tsp- 客户端将返回一个错误 。 以设tsp-地. 子目录中的 yaml 文件, 您可以创建 tsp- 位置 。 手动或使用 Yaml 文件 `tsp-client init` 附有适当 `emitter-output-dir` 配置来创建它 .

需要的文件结构示例 :

```
- sdk/
  - foo/
    - tsp-location.yaml
    - bar/
        - tsp-location.yaml
    - zas/
        - tsp-location.yaml
```

子目录中的正则 tsp-location.yaml 示例 :

```yml
directory: specification/contosowidgetmanager/Contoso.WidgetManager
commit: abc123
repo: Azure/azure-rest-api-specs
additionalDirectories:
  - specification/contosowidgetmanager/Contoso.WidgetManager.Shared/
```

4.  运行 `tsp-client update` 从父目录。 上面的例子就是 `foo/` 目录.

> 注:如果 `update` 调用子目录失败 .

5.  都结束了! tsp-客户端会调用每个子目录上的更新命令,向命令转发命令行参数.

> 注: `local-spec-repo` 旗在批量库生成时会有特殊的行为. tsp客户端将获得传递到旗帜的本地光谱回波路径的回波根路径,然后从 tsp 位置附加目录值. 相应的子目录中的 yaml 文件 .

## 常见问题

### @azure-tools/typespec-client-generator-cli 是什么？

从 TypeSpec 生成 Azure SDK 的工具

### 如何安装 @azure-tools/typespec-client-generator-cli？

在项目目录运行 npm install @azure-tools/typespec-client-generator-cli，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@typespec/compiler（1\.0\.0-rc\.1 \|\| \>=1\.0\.0 \<2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 tsp-client，可以用 npx tsp-client 直接运行。

### @azure-tools/typespec-client-generator-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/azure-tools\_\_typespec-client-generator-cli 是否存在。

### @azure-tools/typespec-client-generator-cli 支持 ESM 还是 CommonJS？

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

### @azure-tools/typespec-client-generator-cli 需要什么版本的 Node\.js？

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

### @azure-tools/typespec-client-generator-cli 可以商用吗？

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

### @azure-tools/typespec-client-generator-cli 的下载量有多少？

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

### @azure-tools/typespec-client-generator-cli 还在维护吗？

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