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交互流程包含三个提示词：
- 模板选择：从可用模板中选择（通过颜色编码以便快速识别）
- 包名：为你的项目指定 npm 包名（根据 npm 命名规范进行验证）
- 覆盖确认：如果目标目录存在且不为空，确认是否清空其内容
非交互模式
为了自动化和 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 遵循系统化的初始化流程：
架构
该 CLI 实现遵循模块化架构，具有清晰的关注点分离：
模块职责：
- index.js：Shebang 包装器，用于导入并执行来自
dist/index.mjs的构建模块 - src/index.ts：主要协调器，处理参数解析、验证和工作流程协调
- src/options.ts：使用
prompts库定义模板和交互式提示词配置 - src/generator.ts：项目生成逻辑，包括模板复制、package.json 定制和文件部署
- src/utils.ts：用于验证、格式化和包管理器检测的工具函数
项目生成流程
生成器对选定的模板执行多项转换：
- 模板复制：将所有文件从选定的模板目录递归复制到目标位置
- 包配置：读取模板的
package.json，使用用户提供的包名更新name字段，并执行字符串替换以替换{{name}}占位符 - 文件部署：将
_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：本地开发，环境类型设置为 localbuild: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 集成：为生成的项目自定义构建流程
参考资料
- 官方文档：https://vtj.pro/
- 在线平台：https://app.vtj.pro/
- 开源仓库：https://gitee.com/newgateway/vtj