快速入门
如果你是个前端开发者，正在寻找一款能真正融入现有工作流的低代码工具，VTJ (VTJ.PRO) 值得花五分钟了解一下。它基于 AI，专为 Vue3 设计，核心能力是让 Vue 源代码和低代码 DSL 之间能双向智能转换——听起来很技术，但上手其实很直接。
快速开始工作流
从零到跑起来，VTJ 的 CLI 工具把过程压缩成了三个步骤：创建项目、安装依赖、启动开发服务器。整个过程不会超过 5 分钟，你就能得到一个低代码开发环境。
graph LR
A[创建项目] --> B[安装依赖]
B --> C[启动开发服务器]创建你的第一个项目
VTJ 提供了 create-vtj 这个 CLI 工具来搭项目。根据你的目标平台和开发需求，可以选择不同的项目类型。
安装命令
根据你的场景，从以下四个命令中挑一个执行即可：
| 项目类型 | 命令 | 描述 |
|---|---|---|
| Web 应用 (PC) | npm create vtj@latest --registry=https://registry.npmmirror.com -- -t app | 针对桌面端优化的标准 Web 应用 |
| H5 应用 (移动端) | npm create vtj@latest --registry=https://registry.npmmirror.com -- -t h5 | 针对移动端优化的 Web 应用 |
| UniApp (跨平台) | npm create vtj@latest --registry=https://registry.npmmirror.com -- -t uniapp | 一次构建，部署到多个平台 |
| 物料开发 | npm create vtj@latest --registry=https://registry.npmmirror.com -- -t material | 开发自定义组件库 |
交互式模板选择
如果省略 -t 参数，CLI 会弹出一个交互式菜单，所有可用模板一目了然，直接选择就行：
? 请选择项目模板:
❯ Web应用( app )
H5应用( h5 )
低代码区块插件( plugin )
移动端应用( uniapp )
物料开发项目( material )
设计器扩展开发项目( extension )
通用类库( library )项目结构概述
项目创建完成后，你会看到一个结构清晰的 Vue3 应用，已经集成了 VTJ。以 Web 应用模板为例，典型结构如下：
vtj-project/
├── public/
│ ├── fa vicon.ico
│ ├── logo.png
│ └── logo.svg
├── src/
│ ├── App.vue # 集成了 XMask 的根组件
│ ├── main.ts # 应用入口点
│ ├── router/ # Vue Router 配置
│ ├── style/ # 全局样式
│ └── views/ # 页面组件
├── package.json # 项目依赖
├── tsconfig.json # TypeScript 配置
└── vite.config.ts # Vite 构建配置开始开发
项目就绪之后，进入目录，安装依赖，启动开发服务器——三行命令的事：
# 进入你的项目目录
cd vtj-project
# 安装依赖
npm install
# 启动开发服务器
npm run dev开发服务器默认会在 https://localhost:5173 上启动（如果端口被占，会自动跳到下一个可用端口）。打开浏览器，你看到的将是一个带有专业布局和导航系统的 VTJ 驱动应用。
理解生成的代码
生成的项目里已经包含了 VTJ 的核心组件和服务。主入口文件里的初始化代码如下：
// main.ts - 应用初始化
const adapter = createAdapter({ loading, notify, Startup, useTitle });
const service = new LocalService(createServiceRequest(notify));
const { provider, onReady } = createProvider({
nodeEnv: process.env.NODE_ENV,
mode: ContextMode.Raw,
modules: createModules(),
adapter,
service,
router,
dependencies: {
Vue: () => import("vue"),
VueRouter: () => import("vue-router"),
Pinia: () => import("pinia"),
VueI18n: () => import("vue-i18n"),
},
project: {
id: name,
},
enableStaticRoute: true,
});这段代码设置提供了几个关键能力：
- Provider System：集中化的状态和服务管理
- Adapter Layer：UI 通知和加载状态处理
- Service Integration：现成的 API 和数据服务抽象
- Module System：动态模块加载能力
- Static Route Support：基于文件的路由系统
可用模板详解
Web 应用 (app)
桌面端 Web 应用的默认模板，带这些功能：
- 完整的 XMask 布局，侧边栏+导航
- Element Plus UI 组件
- 基于路由的页面组织
- 集成的身份验证占位符
- 生产就绪的构建配置
H5 应用 (h5)
针对移动设备优化，特点是：
- 触摸友好的界面
- 响应式设计系统
- 移动端特定的视口处理
- 针对移动浏览器的性能优化
UniApp 模板 (uniapp)
跨平台模板，支持：
- 微信小程序
- H5 Web 应用
- 原生移动应用
- 桌面应用
物料开发
用来创建自定义组件库：
- 独立的开发和构建环境
- VTJ 物料 Schema 集成
- 使用 Vitest 的测试基础设施
- 组件文档支持
接下来做什么？
成功创建并运行第一个 VTJ 项目之后，可以继续深入了解这些方向：
- 安装与环境设置——生产开发的详细环境配置
- 创建 Web 应用——Web 应用开发的深入指南
- 创建 H5 移动应用——移动端特定的开发模式
- 架构概述——了解 VTJ 的核心架构和设计原则
- 引擎 API 参考——低代码引擎的完整 API 文档
常见问题排查
端口已被占用
如果 5173 被占用了，Vite 会自动使用下一个可用端口。看终端输出的实际 URL 就能访问。
依赖安装失败
如果 npm install 失败了，可以试试使用 npm 镜像：
npm install --registry=https://registry.npmmirror.comTypeScript 错误
模板默认包含 TypeScript 配置。如果遇到类型错误，先确认 IDE 的 TypeScript 服务器正常运行，并且所有依赖都已经安装好。
