create-vben-admin 是从 vue-vben-admin Monorepo 按需提取单一 UI 模板 的 npm CLI 脚手架工具,生成可独立安装、独立维护的 Vue 3 + Vite 后台管理项目。
English: README.en.md
| 项目 | 说明 |
|---|---|
| npm 包名 | create-vben-admin |
| 上游真源 | vbenjs/vue-vben-admin |
| 适用框架 | Vue 3 · Vite · TypeScript · pnpm workspace |
| Node | >= 20.11 |
vben-admin(vue-vben-admin)以 Monorepo 维护多套 UI 模板(apps/web-*)与大量共享包(packages/、internal/)。若你只需 一种 UI 库 的起步工程,不必 clone 整个 upstream 仓库。
create-vben-admin 是一条命令的 vben 脚手架生成器:
- 从 GitHub 拉取指定 upstream ref(默认最新 release tag)
- 解析 pnpm workspace 依赖闭包
- 只保留所选
apps/web-*模板及其传递依赖 - 输出 扁平单应用仓库(业务代码在根目录)
- 自动执行
pnpm install与 vendor 预构建
upstream Monorepo create-vben-admin 生成物
───────────────── ─────────────────
apps/web-naive ──提取──► my-app/ ← 业务代码在根目录
packages/* ──闭包──► packages/ ← 构建所需 vendor
internal/* internal/
| 适合 | 不适合 |
|---|---|
| 只要 Ant Design Vue / Element Plus / Naive UI 等 单一 vben 模板 | 需要同时维护 upstream 全部 apps/web-* |
| 希望 轻量本地仓库,减少 Monorepo 认知成本 | 需要与官方 Monorepo 完全等价 的开发体验 |
| 锁定 upstream tag / commit reproducible 生成 | 期望本工具替代官方 vben 文档或长期 fork 维护 |
# 推荐:零安装(需 Node >= 20.11)
pnpm dlx create-vben-admin
# 非交互(目录名 → ~/Downloads/<name>)
pnpm dlx create-vben-admin my-vben-admin --template web-naive --no-mock
# 指定完整路径与 upstream 版本
pnpm dlx create-vben-admin ~/Downloads/my-vben-admin --template web-antd --ref v5.7.0 --force
# 全局安装
pnpm add -g create-vben-admin
create-vben-admin --help交互时 项目路径 默认:~/Downloads/my-vben-admin(可改为任意绝对/相对路径)。
cd ~/Downloads/my-vben-admin
pnpm dev开发端口由生成物 .env.development 的 VITE_PORT 控制(upstream 默认 5888,非 5173)。
模板 ID --template |
UI 库 | upstream 路径 |
|---|---|---|
web-antd |
Ant Design Vue | apps/web-antd |
web-ele |
Element Plus | apps/web-ele |
web-naive |
Naive UI | apps/web-naive |
web-tdesign |
TDesign | apps/web-tdesign |
web-antdv-next |
Ant Design Vue Next | apps/web-antdv-next |
| 选项 | 说明 |
|---|---|
[project-path] |
绝对路径、相对路径,或目录名(→ ~/Downloads/<name>) |
-t, --template |
UI 模板 ID(见上表) |
-r, --ref |
upstream git ref(tag / branch / commit);默认 最新 GitHub release tag |
--mock |
包含 apps/backend-mock(Nitro Mock 服务) |
--no-mock |
不包含 mock(默认;非交互时跳过询问) |
--offline |
仅使用本地 upstream 缓存 |
--force |
覆盖非空目标目录 |
--dry-run |
只解析生成计划,不写文件 |
| 项 | 说明 |
|---|---|
| 输出布局 | 单 package 扁平(app 在根,packages/ / internal/ 保留) |
| upstream ref | 最新 release tag(--ref 可覆盖) |
| backend-mock | 默认不包含;--mock 或交互确认时包含 |
| OpenAPI | 始终从 upstream 生成 docs/mock-api.openapi.json 接口参考 |
| 生成后 | 自动 pnpm install + workspace stub(失败则整次生成失败) |
| 缓存目录 | ~/.create-vben-admin-cache/(环境变量 CREATE_VBEN_ADMIN_CACHE 可覆盖) |
clone 会得到 完整 Monorepo(所有 UI 模板与工具链);create-vben-admin 只提取 一个 apps/web-* 及其 workspace 依赖,输出更小的独立项目。
发布在 npm 上,可用 pnpm dlx、pnpm add -g 或 npm i -g create-vben-admin。生成物默认使用 pnpm(与 upstream 一致)。
读取生成物 .env.development 中的 VITE_PORT,upstream 当前默认 5888。请以终端实际输出为准。
默认 不包含 apps/backend-mock。交互时可选择 --mock 包含;不含 mock 时仍会生成 OpenAPI 参考文档供 Apifox / Postman 导入。
使用 --ref,例如 --ref v5.7.0 或具体 commit SHA。默认取 GitHub 最新 release tag。
请用最新版 CLI 重新 --force 生成。旧生成物若缺少 @vben/vite-config/dist 等 vendor 构建产物,需重新跑完 create-vben-admin 的 install + stub 流程。
不是。 生成物 README 会注明 upstream ref 与 create-vben-admin 版本;这是社区维护的提取工具,非 vbenjs 官方 npm 包。
| 命令 | 说明 |
|---|---|
pnpm install |
安装依赖 |
pnpm dev |
本地运行 CLI(tsx) |
pnpm verify |
format · typecheck · lint · test · build |
pnpm build |
构建 dist/ 供 npm 发布 |
环境: Node >= 20.11 · pnpm · 手动生成物请写入 .temp/generated/(已 gitignore)。
| 文档 | 用途 |
|---|---|
docs/decisions/npm-publish.md |
npm 发布与 GitHub Release |
docs/versions/v1.0.0/dev-guide.md |
里程碑开发指南 |
docs/decisions/ |
架构 / Git / upstream 同步 ADR |
AGENTS.md |
Cursor Agent 入口 |
链接
- 仓库:github.com/379949990/create-vben-admin
- upstream:vbenjs/vue-vben-admin
- Vben 官方文档:doc.vben.pro
MIT