AI 驱动的 Vue3 应用开发平台 深入探究（十九）：CLI与工具链之Create VTJ CLI 参考

Create VTJ CLI 参考

Create VTJ CLI 是 VTJ 项目的官方脚手架工具，提供针对多种平台和用例的预配置项目模板。该 CLI 通过直观的交互界面或命令行参数处理环境设置、依赖配置和样板代码生成，从而简化项目初始化流程。

安装

Create VTJ CLI 可以通过 npm create 命令模式直接调用，无需显式安装。该工具以包名 create-vtj 发布到 npm，当前版本为 0.12.19。

npm create vtj@latest

# 使用自定义镜像源（推荐在中国地区使用以加快下载速度）
npm create vtj@latest --registry=https://registry.npmmirror.com

该 CLI 会通过解析用户代理自动检测你的包管理器（npm、yarn 或 pnpm），并为创建的项目生成相应的安装说明。

可用模板

Create VTJ 提供了七种针对不同开发场景的预配置模板：

模板名称	显示名称	用途	主要依赖
app	Web应用	具有完整 VTJ 设计器集成的 PC 端 Web 应用	@vtj/web, @vtj/pro, vue-router, pinia, vue-i18n
h5	H5应用	移动端优化的 Web 应用	@vtj/renderer, @vtj/h5, vue-router, pinia, vue-i18n
uniapp	移动端应用	跨平台移动应用（微信小程序、H5、App）	@dcloudio/uni-app, @vtj/uni-app, vue-router
material	物料开发项目	用于 VTJ 设计器的自定义组件库开发	@vtj/core, @vtj/web, element-plus
plugin	低代码区块插件	用于低代码引擎的可复用区块/插件	@vtj/core, @vtj/ui, @vtj/icons
extension	设计器扩展开发项目	设计器面板扩展和自定义组件	@vtj/core, @vtj/pro, @vueuse/core
library	通用类库	独立的工具或组件库	unbuild, vitest

CLI 用法

交互模式

不带参数运行 CLI 会启动交互式提示词序列：

npm create vtj@latest

交互流程包含三个提示词：

1. 模板选择：从可用模板中选择（通过颜色编码以便快速识别）
2. 包名：为你的项目指定 npm 包名（根据 npm 命名规范进行验证）
3. 覆盖确认：如果目标目录存在且不为空，确认是否清空其内容

非交互模式

为了自动化和 CI/CD 流水线，可以通过直接指定模板来跳过提示词：

# 创建 Web 应用
npm create vtj@latest -- -t app

# 创建 H5 移动端应用
npm create vtj@latest -- -t h5

# 创建 uni-app 跨平台项目
npm create vtj@latest -- -t uniapp

# 创建物料开发项目
npm create vtj@latest -- -t material

-t 和 --template 标志可以互换使用。其余的提示词（包名和覆盖确认）仍会出现，允许进行半自动化工作流程。

命令行选项

选项	别名	描述	必填	默认值
--template	-t	按名称预选模板	否	提示词用户选择
registry	-	用于 create 命令的 npm 镜像源	否	npm 官方镜像源

CLI 工作流程

Create VTJ CLI 遵循系统化的初始化流程：

flowchart TD A[CLI 执行] --> B{已指定模板?} B -- 是 --> C[验证模板名称] B -- 否 --> D[交互式模板选择] C -- 无效 --> E[显示错误并退出] C -- 有效 --> F[提示词包名] D --> F F --> G{目标目录是否存在?} G -- 否 --> H[创建目录] G -- 是 --> I{目录是否为空?} I -- 是 --> H I -- 否 --> J[提示词覆盖确认] J -- 是 --> L[清空目录] J -- 否 --> K[取消操作] L --> M[复制模板文件] H --> M M --> N[更新 package.json 名称] N --> O[复制 .gitignore 和 .npmrc] O --> P[显示后续步骤]

架构

该 CLI 实现遵循模块化架构，具有清晰的关注点分离：

graph LR index.js --> src/index.ts src/index.ts --> src/options.ts src/index.ts --> src/generator.ts src/index.ts --> src/utils.ts src/options.ts -.-> src/utils.ts src/generator.ts -.-> src/utils.ts

模块职责：

• index.js ：Shebang 包装器，用于导入并执行来自 dist/index.mjs 的构建模块
• src/index.ts：主要协调器，处理参数解析、验证和工作流程协调
• src/options.ts ：使用 prompts 库定义模板和交互式提示词配置
• src/generator.ts：项目生成逻辑，包括模板复制、package.json 定制和文件部署
• src/utils.ts：用于验证、格式化和包管理器检测的工具函数

项目生成流程

生成器对选定的模板执行多项转换：

1. 模板复制：将所有文件从选定的模板目录递归复制到目标位置
2. 包配置 ：读取模板的 package.json，使用用户提供的包名更新 name 字段，并执行字符串替换以替换 {{name}} 占位符
3. 文件部署 ：将 _gitignore 和 _npmrc 从模板根目录分别作为 .gitignore 和 .npmrc 复制到新项目中

💡 包名验证遵循 npm 命名约定，要求小写字母、数字、连字符，以及可选的作用域名称格式（例如 @scope/package-name）。无效名称将在交互式提示词期间触发验证错误。

生成后步骤

成功创建项目后，CLI 会根据检测到的包管理器显示特定于平台的后续步骤：

完成。现在运行：

  cd vtj-project
  npm install
  npm run dev

对于不同的包管理器，命令会相应调整：

• npm ：npm install 和 npm run dev
• yarn ：yarn 和 yarn dev
• pnpm ：pnpm install 和 pnpm run dev

模板特定功能

Web 应用 (app)

app 模板包含环境配置文件（env.json、env.local.json、env.sit.json、env.uat.json）和用于开发的代理配置。它提供了针对多种环境（SIT、UAT、PRE、PROD）的构建目标，并启用了 TypeScript 类型检查。

关键脚本：

• dev：本地开发，环境类型设置为 local
• build:sit/uat/pre/prod：特定环境的生产构建
• clean：使用自定义清理脚本清理构建产物

H5 应用 (h5)

H5 模板包含具有平台特定设置的 vtj 配置字段：

"vtj": {
  "platform": "h5",
  "noMask": true
}

此配置启用了 H5 特定的渲染行为，并在某些操作期间禁用模态覆盖层。

UniApp 模板 (uniapp)

uni-app 模板提供了广泛的多平台构建脚本，支持：

• App 平台：Android、iOS
• 小程序：微信、支付宝、百度、京东、快手、飞书、QQ、头条
• Web：H5 和 SSR 变体
• 快应用：多种供应商实现

该模板包含每个目标平台的全面 uni-app 依赖和类型定义。

物料开发 (material)

物料模板生成双输出包：

• 库构建：用于组件使用的 UMD 和 ESM 格式
• 物料构建：用于 VTJ 设计器集成的专用格式

exports 字段定义了多个入口点，实现了灵活的导入策略。

故障排除

模板名称验证

如果通过 -t 指定了无效的模板名称，CLI 将显示错误消息并退出，不会创建任何目录：

Error: invalid template name "invalid-name"

有效的模板名称为：app、h5、plugin、uniapp、material、extension、library。

包名验证

包名必须遵守 npm 命名规则：

• 必须以字母或数字开头
• 可以包含字母、数字、连字符和下划线
• 可以包含作用域前缀（例如 @organization/name）
• 最大长度为 214 个字符
• 不能包含空格或特殊字符

无效名称将触发：项目包名不合法，请更换！

目录覆盖保护

默认情况下，CLI 会阻止覆盖非空目录。用户必须在提示词时明确确认覆盖操作。取消提示词将保留现有目录内容。

后续步骤

创建 VTJ 项目后，建议探索以下相关文档主题：

• 创建 Web 应用：app 模板项目的详细指南
• 创建 H5 移动应用：移动端特定的开发模式
• 架构概述：了解 VTJ 系统架构
• 创建自定义物料组件：物料模板项目的指南
• 构建配置和 Vite 集成：为生成的项目自定义构建流程

参考资料

• 官方文档：vtj.pro/
• 在线平台：app.vtj.pro/
• 开源仓库：gitee.com/newgateway/...