AI 驱动的 Vue3 应用开发平台入门指南（二）：快速入门快速入门本指南将帮助你开始使用 VTJ (VTJ.PRO

快速入门

本指南将帮助你开始使用 VTJ (VTJ.PRO) —— 一个基于 AI 的 Vue3 低代码开发平台，支持 Vue 源代码与低代码 DSL 之间的双向智能转换。专为前端开发者设计，可以无缝集成到你现有的开发工作流中。

快速开始工作流

使用 CLI 工具可以轻松开始使用 VTJ。该过程包括三个主要阶段：创建项目、安装依赖和启动开发服务器。

graph LR
    A[创建项目] --> B[安装依赖]
    B --> C[启动开发服务器]

整个过程不到 5 分钟，你将拥有一个功能完善的低代码开发环境。

创建你的第一个项目

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 )

项目结构概述

创建项目后，你将获得一个结构良好的、集成了 VTJ 的 Vue3 应用。以下是 Web 应用模板的典型结构：

vtj-project/
├── public/                 │   ├── favicon.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

开发服务器默认将在 http://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.com

TypeScript 错误

模板包含 TypeScript 配置。如果遇到类型错误，请确保你的 IDE 的 TypeScript 服务器运行正确且所有依赖已安装。

所有生成的项目都使用相同的 @vtj/web 包，该包提供了完整的运行时环境，包括 provider、renderer 和所有 UI 组件。这确保了所有项目类型的一致性，并使升级到新版本变得简单。

CLI 工具支持覆盖确认。如果你在现有目录中创建项目，系统将提示你确认是否在创建新项目之前清除目录内容。

AI 驱动的 Vue3 应用开发平台 入门指南（二）：快速入门