vite-plugin-openapi-ts CLI 使用指南

建议先看插件本体的介绍

vite-plugin-openapi-ts 除了以 Vite 插件的形式在开发 / 构建阶段自动生成代码外，还提供了一套独立的 命令行工具（CLI） 。

CLI 更适合以下场景：

在 CI / CD 流水线里，先生成类型和客户端，再进行构建与测试；
在 monorepo 中集中生成，再给多个子应用复用；
本地需要"只生成一次看结果"，不想依赖 Vite 启动过程。

下面是这套 CLI 的完整用法说明。

安装与基础命令

CLI 入口已经通过 bin 字段绑定为 openapi-ts，安装插件后就可以直接使用：

bash 复制代码

pnpm add -D vite-plugin-openapi-ts

# 本地调用
npx openapi-ts --help

目前内置的几个核心子命令是：

openapi-ts generate：从 OpenAPI 规范生成 TypeScript 类型和 API 客户端；
openapi-ts clean：清理生成的 schemes.ts / index.ts 以及可选缓存文件；
openapi-ts clean-cache：只清理缓存文件 .openapi-cache.json。

你也可以使用简写：

openapi-ts gen 或 openapi-ts g 等价于 openapi-ts generate。

使用 openapi.config.json 进行配置

CLI 支持从当前工作目录下读取 openapi.config.json 作为默认配置，然后再由命令行参数进行覆盖。

一个典型的 openapi.config.json 示例：

json 复制代码

{
  "url": "http://localhost:8080/v3/api-docs",
  "baseUrl": "http://localhost:8080",
  "outputDir": "src/openapi",
  "enableCache": true,
  "skipTimeout": 0,
  "force": false
}

在有了这个文件之后，你可以直接运行：

bash 复制代码

npx openapi-ts generate

此时 CLI 会按如下优先级合并配置：

命令行参数（最高优先级）；
openapi.config.json 中的字段；
内置默认值（例如 outputDir 默认为 src/openapi）。

例如：

最终 url 来源：--url > openapi.config.json 中的 url；
最终 baseUrl 来源：--base-url > openapi.config.json.baseUrl >（远程地址时自动从 url 提取）；
最终 outputDir 来源：--output-dir > openapi.config.json.outputDir > 默认值 src/openapi。

如果既没有在命令行传 --url，也没有在配置文件里配置 url，CLI 会给出错误提示并退出。

generate：生成类型和客户端

generate 是 CLI 中最核心的命令，用于根据 OpenAPI 规范生成类型文件和 API 客户端。

命令参数

bash 复制代码

openapi-ts generate \
  --url        <specUrl>   \ # OpenAPI 文档地址（JSON 或 YAML）
  --base-url   <baseUrl>   \ # API 基础地址，可选
  --output-dir <outputDir> \ # 输出目录，默认 src/openapi
  --enable-cache           \ # 启用缓存（默认 true）
  --skip-timeout <ms>      \ # 跳过超时时间（毫秒）
  --force                    # 强制重新生成，忽略缓存

其中：

--url / -u：OpenAPI 规范地址，支持 http(s) 和本地文件路径；
--base-url / -b：生成客户端时使用的基础地址；
- 如果是远程 http(s) 地址且未显式提供 baseUrl，CLI 会自动尝试从 url 中提取（形如 protocol://host）；
- 如果是本地文件路径，且未提供 baseUrl，CLI 会提示你必须提供一个 baseUrl（可以写在配置文件中）。
--output-dir / -o：生成文件输出目录，默认是 src/openapi；
--enable-cache / -c：是否启用缓存，默认开启；缓存文件为 {outputDir}/.openapi-cache.json；
--skip-timeout / -t：在启用缓存的情况下，如果与上次生成间隔时间小于该值（毫秒），且 url / baseUrl 未发生改变，则会跳过本次生成；
--force / -f：强制重新生成，忽略缓存逻辑。

常见用法示例

完全依赖配置文件：

bash 复制代码

npx openapi-ts generate

只要在 openapi.config.json 中提供了 url（以及可选的其他字段），就可以这样使用。

在配置基础上临时覆盖部分字段：

bash 复制代码

npx openapi-ts generate \
  --url http://localhost:8081/v3/api-docs \
  --force

这里会覆盖配置文件中的 url，并且强制重新生成（无视缓存）。

不使用配置文件，仅命令行参数驱动：

bash 复制代码

npx openapi-ts generate \
  --url ./openapi.yaml \
  --base-url https://api.example.com \
  --output-dir src/openapi

当 url 是本地文件路径时，baseUrl 必须显式提供（或写在 openapi.config.json 里），否则 CLI 会报错。

clean：清理生成文件

clean 命令用于清理通过 CLI 或插件生成的文件：

bash 复制代码

openapi-ts clean \
  --dir         <outputDir> \
  --clean-cache           # 是否同时清理缓存，默认 true

默认会删除 {outputDir}/schemes.ts 和 {outputDir}/index.ts；
如果 --clean-cache 为 true（默认），还会删除 {outputDir}/.openapi-cache.json。

典型用法：

bash 复制代码

npx openapi-ts clean

配合 openapi.config.json 或默认值使用时，会清理 src/openapi 下的生成内容。

在需要"重新完整生成"或重置生成状态时，这个命令非常有用。

clean-cache：仅清理缓存

如果你只想清理缓存文件，而保留已经生成好的类型和客户端，可以使用 clean-cache：

bash 复制代码

openapi-ts clean-cache --dir src/openapi

这条命令只会删除指定目录下的 .openapi-cache.json，不会影响已有的 schemes.ts 和 index.ts。

在 npm scripts / CI 中使用

推荐把 CLI 命令封装到 package.json 里，方便团队成员统一使用：

json 复制代码

{
  "scripts": {
    "openapi:gen": "openapi-ts generate",
    "openapi:clean": "openapi-ts clean",
    "openapi:clean-cache": "openapi-ts clean-cache"
  }
}

然后在命令行中直接执行：

bash 复制代码

pnpm openapi:gen

在 CI 场景里，可以在构建前插入一段：

bash 复制代码

pnpm openapi:gen
pnpm build

这样可以确保生成的类型与服务端 OpenAPI 规范保持最新，从而在前端构建阶段就发现接口不兼容的问题。

小结

CLI 适合在 Vite 之外的场景使用，例如 CI、独立脚本或 monorepo 根目录；
通过 openapi.config.json + CLI 参数覆盖的机制，可以兼顾"统一配置"和"局部灵活调整"；
generate 负责生成，clean / clean-cache 负责回收和重置，搭配使用可以构建出一套比较完整的接口代码生成流程。

在更完整的项目介绍 / 推荐文章中，你可以将本文件的内容作为"CLI 使用章节"直接嵌入；如果你只想单独介绍命令行用法，也可以单独发布这一篇。