kubb-labs/kubb · 上手攻略

仓库：kubb-labs/kubb
链接：https://github.com/kubb-labs/kubb
分类：engineering / 代码生成 / OpenAPI → TypeScript 工具链
作者：spark
更新：2026-10-15

§0 自检(三证 checklist)

✅ GitHub URL 已 fetch:仓库 README(2026-10-14 抓取)、kubb.dev 官方站(2026-10-14 抓取)对齐核对。
⚠️ 顶会/学术 venue:Kubb 是 MIT 协议工具,非论文落地项目,无 anchor 学术 venue。
✅ README 子模块 anchor 已列:kubb.config.ts 配置文件、@kubb/adapter-oas 适配器、kubb/kit 自定义工具包、unplugin-kubb 打包器插件、MCP server(@kubb 内置)、Kubb Studio。

关键事实引用全部 verbatim 来自 README/kubb.dev:OpenAPI 2.0/3.0/3.1、14 个官方插件、MIT 协议、Stijn Van Hulle 主理、kubs.dev 版本 5.x 系列。版本号具体小版本未在 README 露出,凡用版本号请以 npm view kubb version 实时为准。

1. 它是什么?解决什么问题?

Kubb 是 "把 API 规范(spec 当 Spec)编成类型安全代码" 的代码生成器。输入一份 OpenAPI 2.0 / 3.0 / 3.1 规范(支持 $ref、oneOf 等),输出:

TypeScript types
类型安全的 axios 或 Fetch 客户端(状态码映射、auth、validation、文件上传、SSE、interceptor、可换 transport)
TanStack Query / SWR hooks
Zod 校验器
Faker mock 数据
MSW 拦截处理器
顺带能生成 Cypress、Redoc、Vue Query、MCP server 等

一句话:OpenAPI 是唯一真相源,Kubb 保证前端代码永远和后端契约同步,再也不用手动维护 types/api.ts。

它要解决的痛点很经典:前端手抄后端 DTO,改一处忘了改三处。Kubb 把"复制粘贴"换成"按规范生成",改 schema → 重跑 → 全栈同步。

2. 快速安装

支持 bun / pnpm / npm:

bun add kubb
# 或
pnpm add kubb
# 或
npm install kubb

写好 OpenAPI 规范(比如 petstore.yaml)之后,跑向导生成 kubb.config.ts:

npx kubb init          # 创建 package.json(若有)、引导选插件、装包、写配置
npx kubb generate      # 按 kubb.config.ts 出代码

npx kubb init 和 npx kubb generate 两条命令 verbatim 来自 README,未独立验证 bin 入口最新版本。README 未明确 init 的选项行为,首次跑建议在干净仓库试,避免覆盖已有 package.json。

3. 核心用法

3.1 三段式流水线(kubb.dev 描述)

01 · Adapt    适配器把你的 spec 解析成统一 AST
02 · Generate 插件从 AST 生成 types / clients / hooks / validators / mocks
03 · Print    解析器把结果写成 TypeScript 或 Markdown 文件(barrel、格式化自动)

Kubb 的设计原则:加一个插件不会改变其它插件的行为。所有插件读同一份 AST。

3.2 14 个官方插件(README 列举 + kubb.dev "14 official plugins")

插件	用途
`@kubb/plugin-ts`	TypeScript types
`@kubb/plugin-axios`	axios 客户端
`@kubb/plugin-fetch`	Fetch 客户端
`@kubb/plugin-react-query`	TanStack Query hooks
`@kubb/plugin-vue-query`	Vue Query hooks
`@kubb/plugin-swr`	SWR hooks
`@kubb/plugin-zod`	Zod 校验器
`@kubb/plugin-faker`	Faker mock 数据
`@kubb/plugin-msw`	MSW 拦截处理器
`@kubb/plugin-cypress`	Cypress 测试
`@kubb/plugin-redoc`	Redoc 文档
`@kubb/plugin-mcp`	MCP server
`@kubb/plugin-oas`(adapter)	OpenAPI 2.0/3.0/3.1 → AST
`@kubb/kit`	自定义插件 / 生成器 / 适配器 / 渲染器的创作工具包(含 JSX 渲染)

按需启用,插件可以独立配置输出目录、文件分组、操作过滤。

3.3 输出控制

按 tag 分组
包含 / 排除 operation
写到 磁盘、内存、或自定义 storage backend 等
通过 kubb/kit 写自己的生成器

3.4 跟打包器集成:`unplugin-kubb`

支持 Vite / Nuxt / Astro / webpack(README 列举)。换句话说,改 spec → dev server HMR 触发生成,所见即所得。

3.5 AI 友好:内置 MCP server

README 原文:"Drive generation from AI tools over the built-in MCP server (Claude, Cursor) or inside Claude Code."

也就是 Claude / Cursor 这类 IDE 可以通过 MCP 直接调用 Kubb 的工具,实现 "告诉 AI '给这个 schema 加分页参数',AI 改 schema → 触发 Kubb 重生成"。

Kubb Studio 是配套的可视化伴侣:浏览器里配 Kubb、跑生成、看 diff。可以连本地项目、连共享沙盒、或者从 CI 发可 review 的 snapshot(kubb-labs/action)。Kubb 本身仍 MIT,可不依赖 Studio 单独用。

3.6 一个最小配置长什么样

README 没贴完整 kubb.config.ts 示例(可能写在文档站),但从 npx kubb init 的行为反推大致结构:

// kubb.config.ts(典型形态,具体字段以文档为准)
import { defineConfig } from '@kubb/core'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'
import { pluginZod } from '@kubb/plugin-zod'
import { pluginFaker } from '@kubb/plugin-faker'

export default defineConfig({
  input: { path: './petstore.yaml' },
  output: { path: './src/gen' },
  plugins: [pluginTs(), pluginAxios(), pluginZod(), pluginFaker()],
})

⚠️ 未独立验证:@kubb/core 是否导出 defineConfig、插件函数是否需要 () 调用、input.path 字段名等都按 README/kubb.dev 的常规命名反推,实际配置以 kubb.dev 文档为准。建议第一次跑通 npx kubb init 看生成的样板,再改。

4. 典型适用场景

BFF / 全栈 TS 项目:后端 OpenAPI 写好,前端直接消费类型 + client + hooks,不用手抄。
微服务聚合:多份 OpenAPI spec → 多组生成目录,统一打包。
SDK 仓库:公司给客户/前端团队的 SDK,以前靠人写,现在按 spec 自动生成。
Mock 优先开发:后端还没好,前端用 @kubb/plugin-faker + @kubb/plugin-msw 直接拿 mock 数据跑。
AI 辅助重构:接 Claude/Cursor,改 schema → AI 通过 MCP 触发生成 → 立刻看到全栈 diff。
CI 上锁契约:kubb-labs/action 在 PR 上发"spec 改了 → 生成的代码也变了"的快照,review 即可控。

5. 坑与注意

npx kubb init 的覆盖风险:README 说"creates a package.json if needed",意味着已有 package.json 时行为需谨慎;首次建议在干净目录试。
OpenAPI 版本边界:支持 2.0 / 3.0 / 3.1,但用了不规范的扩展字段(x- 自定义)时,适配器是否原样透传 README 没明说,踩坑前先在 petstore 上验。
插件之间的耦合:README 强调"加一个插件不改变其它插件",但 plugin-axios + plugin-fetch 同时启用就两个 client 都生成,需要手动 include / exclude 限制。README 没演示如何互斥。
生成的代码进 git 还是 .gitignore? README/kubb.dev 未表态;常规做法是进 git(便于 review diff),但 CI 上锁定"生成代码必须等于当前 spec 输出"可以彻底消除手改风险。
Kubb Studio 是闭源伴侣,README 强调"Kubb remains MIT-licensed and works without Studio",但 Studio 本身授权 README 未列,需要去 kubb.studio 自查。
MCP server 的安全性:在 Claude / Cursor 里挂 MCP 等于让 LLM 直接调本地生成任务,对生产 repo 要考虑沙盒目录或只读 spec。
plugin-mcp 输出的 MCP server 暴露哪些工具 README 没列,要去看 plugin-mcp 包文档。
unplugin-kubb 的 HMR 行为:README 提了"在 Vite/Nuxt/Astro/webpack 里跑",但触发条件(是监听 spec 文件改动还是监听整个 input 目录)未明示。
TypeScript strict 模式兼容:生成的代码默认 strict 友好,但若你的项目开了特别严的 noUncheckedIndexedAccess,要看 plugin-ts 是否处理。
贡献者名单里 Stephen Zhou(hyoban) 在 contributor 列表里出现——README 没解释他和项目的关系,只列 GitHub 主页 hyoban.cc,不能据此推测角色。
依赖 sponsor:README 原话"its development is funded entirely by sponsors",意味着项目维护节奏跟赞助挂钩,采用前最好查 GitHub Sponsors 页面看活跃度。
Discord 支持:README 给的 discord.gg/4dQjA6vrWX 链接未独立验证是否仍有效。

6. 与同类对比

工具	输入	输出	生态广度	关键差异
Kubb	OpenAPI 2.0/3.0/3.1	TS / axios / Fetch / TanStack / SWR / Zod / Faker / MSW / MCP	14 官方插件 + kit 自定义	唯一原生 MCP + Studio 视觉伴侣
openapi-generator	OpenAPI	多语言(含 TS、Java、Go 等)	极广	模板引擎老派,生成 TS 类型不强
openapi-typescript	OpenAPI 3.x	仅 TypeScript types	单点	极轻量,只做 types,不生成 client/hooks
orval	OpenAPI 3.x	TS + axios/React Query/SWR	中等	跟 Kubb 功能最像,生态略小
swagger-codegen	OpenAPI / Swagger	多语言	广	老牌,模板自定义门槛高
speakeasy	OpenAPI	多语言 SDK	商业化	商业产品,适合企业 SDK 团队

Kubb 的独特定位:MCP 友好 + Studio 可视化 + 插件解耦,对于"全栈 TS + 用 Claude/Cursor 开发 + 想锁契约"的团队是当下最丝滑的选项。

7. 一句话推荐

OpenAPI 是你团队的真源,前端又用 TS + React/Vue + Zod + MSW——直接选 Kubb,npx kubb init 五分钟搭起来,装齐 14 插件 + MCP,Claude/Cursor 直接对话改 API。

8. 资源链接

仓库:https://github.com/kubb-labs/kubb
文档:https://kubb.dev
Studio:https://kubb.studio
Studio 接本地项目:https://kubb.dev/docs/5.x/integrations/studio
Claude Code 集成:https://kubb.dev/docs/5.x/ai/claude
GitHub Action:https://github.com/kubb-labs/action
插件库:https://github.com/kubb-labs/plugins
OpenAPI 适配器:@kubb/adapter-oas
赞助页:https://github.com/sponsors/stijnvanhulle 或 https://opencollective.com/kubb
Discord:https://discord.gg/4dQjA6vrWX