VTJ：快速开始

踩着两条虫
18 阅读5分钟

简介

VTJ 是一款基于 Vue3 + TypeScript 的低代码页面可视化设计器，内置低代码引擎、渲染器与代码生成器，面向前端开发者，开箱即用。它支持多种本地体验方式与项目模板，帮助不同技术背景的开发者快速上手。

  • 在线体验入口：app.vtj.pro
  • 官方文档与更多资源请参见项目根目录文档与 README

项目结构

本仓库采用 Monorepo 结构，使用 Lerna + PNPM Workspace 管理多包与工作流。根目录提供统一的脚本与引擎，create-vtj 提供脚手架模板与初始化逻辑；apps 下包含多种示例应用模板（Web、H5、UniApp、物料开发等），便于快速体验与二次开发。

graph TB
Root["根目录<br/>package.json / lerna.json / pnpm-workspace.yaml"] --> Scripts["统一脚本与引擎"]
Root --> CreateVTJ["脚手架 create-vtj<br/>src/index.ts / src/options.ts"]
CreateVTJ --> Templates["模板集合<br/>app / h5 / uniapp / material 等"]
Root --> Apps["示例应用 apps/<br/>app / h5 / uniapp / material / extension"]
Root --> Docs["文档 docs/"]
Root --> Packages["核心包 packages/*"]
Root --> Platforms["平台层 platforms/*"]

核心组件

  • 统一脚本与引擎：根目录提供 setup、build、dev、app:dev 等脚本，覆盖本地开发与构建流程。
  • 脚手架 create-vtj：提供 npm create vtj 命令，支持多种模板选择与交互式参数输入。
  • 模板系统：内置 Web 应用、H5 应用、UniApp 跨端应用、物料开发等模板，分别对应不同的运行与构建策略。
  • 工作区与包管理：Lerna + PNPM Workspace 统一管理多包发布与依赖解析。

架构总览

下图展示了从“环境准备”到“首次启动”的整体流程，以及脚手架模板与示例应用之间的关系。

flowchart TD
Start(["开始"]) --> Env["环境准备<br/>Node >= 20 / nvm 切换 / 全局安装 lerna / pnpm"]
Env --> Online["在线体验<br/>访问 app.vtj.pro"]
Env --> Local["本地开发体验<br/>git clone -> npm run setup -> npm run build -> npm run app:dev"]
Env --> Scaffolding["脚手架创建项目<br/>npm create vtj@latest -- -t <模板>"]
Scaffolding --> TemplateApp["模板: Web 应用(app)"]
Scaffolding --> TemplateH5["模板: H5 应用(h5)"]
Scaffolding --> TemplateUni["模板: UniApp(uniapp)"]
Scaffolding --> TemplateMaterial["模板: 物料开发(material)"]
Local --> DevServer["开发服务器启动<br/>app:dev / h5:dev / uniapp:dev"]
DevServer --> Preview["预览与调试"]
Online --> Done(["完成"])
Preview --> Done

详细组件分析

环境准备与前置条件

  • Node.js 版本要求：Node >= 20（建议使用 nvm 进行版本切换）
  • 全局工具：全局安装 Lerna 与 PNPM
  • 镜像源：推荐使用国内镜像源以提升安装速度

在线体验（app.vtj.pro）

  • 访问 app.vtj.pro 即可在线体验设计器与出码能力
  • 适合快速试用与演示场景

本地开发体验（推荐）

  • 步骤一：克隆仓库
  • 步骤二：初始化与构建
  • 步骤三：启动开发服务器

四种项目模板的创建方法

脚手架命令：npm create vtj@latest --registry=registry.npmmirror.com -- -t <模板>

模板类型与命令：

  • Web 应用（PC 端）：-t app
  • H5 应用（移动端）：-t h5
  • UniApp 跨端应用：-t uniapp
  • 物料开发项目：-t material

脚手架入口与模板选项：

  • 入口文件：create-vtj/src/index.ts
  • 模板列表与交互：create-vtj/src/options.ts
  • 模板清单与脚本：
    • app 模板：create-vtj/templates/app/package.json
    • h5 模板：create-vtj/templates/h5/package.json
    • uniapp 模板：create-vtj/templates/uniapp/package.json
    • material 模板：create-vtj/templates/material/package.json

首次启动完整流程

  • git clone 仓库
  • npm run setup（安装依赖）
  • npm run build（构建所有包）
  • npm run app:dev（启动 Web 应用开发服务器）

各模板的构建与开发差异

  • Web 应用（app）：使用 @vtj/cli 创建 Vite 配置，并集成本地开发工具
  • H5 应用（h5）：使用 @vtj/cli 与 @vtj/pro 的开发工具插件
  • UniApp（uniapp）：使用 @vtj/cli 的 UniApp 配置，结合 @dcloudio/vite-plugin-uni
  • 物料开发（material）：使用 @vtj/cli，支持库与物料分别构建

依赖关系分析

  • 包管理与工作区：根目录通过 pnpm-workspace.yaml 声明工作区范围，lerna.json 指定使用 pnpm 作为包管理器并启用 Nx。
  • 脚本分层：根脚本负责统一调度各子包的测试、构建与发布；示例应用与模板各自维护独立的开发与构建脚本。
  • 脚手架与模板：create-vtj 作为独立包，提供模板与交互式参数，模板内声明各自依赖与构建脚本。
graph LR
Pkg["根 package.json<br/>scripts / engines"] --> Lerna["lerna.json<br/>npmClient=pnpm / useNx"]
Pkg --> WS["pnpm-workspace.yaml<br/>工作区范围"]
Pkg --> CreateVTJ["create-vtj<br/>脚手架入口与模板"]
CreateVTJ --> TApp["模板 app/package.json"]
CreateVTJ --> TH5["模板 h5/package.json"]
CreateVTJ --> TUni["模板 uniapp/package.json"]
CreateVTJ --> TMaterial["模板 material/package.json"]

性能注意事项

  • 使用国内镜像源安装依赖，减少网络波动带来的耗时。
  • 首次构建建议在空闲时段进行，避免同时运行多个大型任务。
  • 模板选择应根据目标平台与设备特性决定，避免不必要的依赖与打包体积。

故障排查指南

常见问题与解决思路：

  • 端口冲突
    • 现象：开发服务器无法启动或端口被占用
    • 处理：修改模板或应用的 Vite 配置中的端口设置，或关闭占用进程
    • 参考：各模板的 vite.config.ts 中的端口与代理配置
  • 依赖安装失败
    • 现象：pnpm 或 npm 安装报错
    • 处理：确认 Node >= 20；使用国内镜像源；清理缓存后重试
    • 参考：根 package.json 的 engines 与脚本
  • 热更新异常
    • 现象：保存文件后未触发热更新
    • 处理：检查模板的 Vite 插件配置；确保未禁用 HMR；检查代理与跨域设置
    • 参考：各模板的 vite.config.ts 与 proxy.config.ts（模板内存在）

结论

通过本快速开始指南，你可以：

  • 准备好符合要求的开发环境（Node >= 20、全局安装 Lerna 与 PNPM）
  • 选择在线或本地方式快速体验 VTJ
  • 使用 npm create vtj 命令创建四种模板项目
  • 完成首次启动与开发调试
  • 面对常见问题时具备基础排查能力

附录

附录A：脚手架模板清单与用途

  • app：Web 应用（PC 端），适合传统浏览器页面开发
  • h5：H5 移动端应用，适配移动端浏览
  • uniapp：跨端应用，支持多端编译与运行
  • material：物料开发项目，用于构建可复用的组件与页面物料

附录B：本地开发常用脚本

  • 初始化与构建：npm run setup、npm run build
  • 启动开发服务器：npm run app:dev、npm run h5:dev、npm run uniapp:dev
  • 清理与重置：npm run clean、npm run reset

参考资料

VTJ.PRO 是一个开源的、AI 驱动的 Vue 3 企业级应用开发平台。它通过 AI 智能体与可视化编排实现高效开发，并支持导出标准 Vue 代码以避免平台锁定。更多信息请访问：

avatar
文章
阅读
粉丝