创建 Web 应用
VTJ.PRO 提供了一个功能强大的 CLI 工具，使开发者能够使用现代 Vue3 + TypeScript 技术栈快速搭建 Web 应用程序。create-vtj 工具会生成一个生产就绪的项目结构，其中预配置了包含 Element Plus UI 组件库、Vue Router 路由、Pinia 状态管理以及完整的构建配置在内的核心依赖。这种方法在大幅减少初始搭建时间的同时，保持了对定制需求的灵活性。
Web 应用程序模板专为 PC/桌面端应用程序设计，配备完整的低代码开发环境。通过使用 VTJ 的脚手架系统，你可以在几分钟内创建一个功能完备的 Web 应用程序，并将低代码引擎、渲染器和代码生成能力无缝集成到你的开发工作流中。
快速入门指南
使用官方 CLI 工具创建 VTJ Web 应用程序非常简单。该 CLI 支持交互模式（提示你进行配置选项）和用于自动化设置的命令行参数。对于初学者，交互模式会在每个配置步骤提供指导，而有经验的开发者则可以使用直接的命令行参数来更快地创建项目。
要创建一个新的 Web 应用程序，请在终端中执行以下命令：
npm create vtj@latest --registry=https://registry.npmmirror.com -- -t app
此命令启动项目创建过程，具有以下特征：
npm create vtj@latest调用官方 VTJ 脚手架工具--registry=https://registry.npmmirror.com确保从中国镜像快速下载-t app指定 Web 应用程序模板（或者，使用--template app）
执行期间，系统将提示你提供：
- 项目模板 - 使用
-t app时预选为 "Web应用" - 项目包名称 - 默认为
vtj-project，但应进行自定义 - 覆盖确认 - 仅当目标目录不为空时出现
项目创建后，CLI 会提供清晰的说明，用于初始化依赖和启动开发服务器。
项目初始化工作流
项目创建过程遵循系统化的方法，确保你的 Web 应用程序得到正确配置。以下是完整工作流的可视化表示：
flowchart TD
A[执行 CLI 命令] --> B{是否指定模板?}
B -- "是, -t app" --> C[验证模板]
B -- "否" --> D[提示模板选择]
D --> E[选择 Web 应用程序]
C --> F[提示包名称]
E --> F
F --> G[提示覆盖确认]
G --> H[创建目标目录]
H --> I[复制模板文件]
I --> J[更新 package.json]
J --> K[创建 .gitignore]
K --> L[创建 .npmrc]
L --> M[显示设置说明]
M --> N[安装依赖]
N --> O[启动开发服务器]
可用模板
VTJ 提供多种项目模板以适应不同的开发场景。使用交互模式时，你可以从以下选项中进行选择：
| 模板名称 | 显示名称 | 使用场景 | 颜色代码 |
|---|---|---|---|
app | Web应用 | 标准 PC/桌面 Web 应用程序 | 绿色 |
h5 | H5应用 | 移动端 Web 应用程序 | 黄色 |
plugin | 低代码区块插件 | 低代码区块插件 | 浅红色 |
uniapp | 移动端应用 | 跨平台移动应用程序 | 青色 |
material | 物料开发项目 | 自定义物料/组件开发 | 浅红色 |
extension | 设计器扩展开发项目 | 设计器扩展开发 | 浅红色 |
library | 通用类库 | 可复用的库包 | 洋红色 |
对于 Web 应用程序，app 模板提供了最佳起点，预配置了桌面特定的功能、综合路由系统以及与 VTJ Web 平台能力的完整集成。
项目结构
生成的 Web 应用程序遵循结构良好的组织方式，实现了关注点分离并保持了可扩展性。理解此结构对于有效开发和自定义 VTJ 应用程序至关重要。
vtj-project/
├── public/ │ ├── favicon.ico
│ ├── logo.png
│ └── logo.svg
├── src/ # 应用程序源代码
│ ├── App.vue # 带有 XMask 布局的根组件
│ ├── main.ts # 应用程序入口
│ ├── assets/ # 本地资源 (图片, 字体)
│ │ ├── logo.png
│ │ └── logo.svg
│ ├── components/ # 可复用的 Vue 组件
│ │ └── HelloWorld.vue
│ ├── router/ # Vue Router 配置
│ │ └── index.ts
│ ├── style/ # 全局样式和主题
│ │ └── index.scss
│ └── views/ # 页面级组件
│ ├── not-found.vue
│ └── unauthorized.vue
├── env.json # 特定环境变量
├── env.local.json # 本地开发变量
├── env.sit.json # SIT 环境变量
├── env.uat.json # UAT 环境变量
├── proxy.config.ts # Vite 代理配置
├── vite.config.ts # Vite 构建配置
├── tsconfig.json # TypeScript 配置
├── tsconfig.node.json # Node TypeScript 配置
└── package.json # 项目依赖和脚本
核心应用程序文件
VTJ Web 应用程序的入口是 src/main.ts，它使用所有必要的 VTJ 集成初始化 Vue 应用程序。该文件演示了 VTJ 如何将传统的 Vue 开发与低代码能力无缝结合：
import { createProvider, LocalService, createModules, ... } from '@vtj/web';
import { createApp } from 'vue';
import router from './router';
import App from './App.vue';
const app = createApp(App);
const adapter = createAdapter({ loading, notify, Startup, useTitle });
const service = new LocalService(createServiceRequest(notify));
const { provider, onReady } = createProvider({
nodeEnv: process.env.NODE_ENV as NodeEnv,
mode: ContextMode.Raw,
modules: createModules(),
adapter,
service,
router,
dependencies: { Vue, VueRouter, Pinia, VueI18n },
project: { id: name },
enableStaticRoute: true
});
onReady(async () => {
app.use(router);
app.use(provider);
app.use(IconsPlugin);
app.mount('#app');
});
src/App.vue 组件实现了 XMask 布局系统，它提供了一个包含导航、菜单和操作栏的完整应用程序外壳。该组件预配置了 Element Plus 本地化和一组默认操作按钮（消息、锁、注销），你可以根据需要自定义这些按钮。
Provider 配置中的
ContextMode.Raw模式表明应用程序以标准 Vue 模式运行，而不是设计器模式。这对于要在没有设计器界面的情况下渲染页面的生产应用程序至关重要。
配置和环境管理
VTJ 应用程序通过 JSON 配置文件支持复杂的环境管理，从而实现开发、测试和生产环境之间的无缝切换。这种方法在不修改源代码的情况下分离了特定环境的配置。
环境配置文件
模板包含多个环境配置文件：
| 文件 | 用途 | 使用场景 |
|---|---|---|
env.json | 默认环境变量 | 所有环境共享的配置 |
env.local.json | 本地开发覆盖 | 带有本地 API 端点的开发环境 |
env.sit.json | SIT 环境变量 | 系统集成测试 (SIT) 环境 |
env.uat.json | UAT 环境变量 | 用户验收测试 (UAT) 环境 |
这些文件定义了可在整个应用程序中访问的键值对，通常用于 API 端点、功能标志和特定平台的配置。ENV_TYPE 环境变量控制在构建过程中激活哪个配置。
代理配置
proxy.config.ts 文件配置 Vite 开发服务器代理，允许在本地开发期间进行无缝 API 调用，而不会出现 CORS 问题：
export default {
"/api": {
target: "https://sso-sit.newpearl.com",
changeOrigin: true,
ws: true,
},
};
此配置将所有以 /api 开头的请求转发到指定的目标服务器，并为实时功能启用了 WebSocket 支持。你应该自定义目标 URL 以匹配你的开发或暂存 API 端点。
开发和构建工作流
VTJ 提供了一套用于开发、构建和部署的综合脚本。这些脚本在 package.json 中定义，可以使用 npm 或你首选的包管理器执行。
可用脚本
| 命令 | 环境 | 描述 |
|---|---|---|
npm run dev | 本地开发 | 启动带有热模块替换的开发服务器 |
npm run build | 生产 | TypeScript 检查和生产构建 |
npm run build:sit | SIT | TypeScript 检查和 SIT 环境构建 |
npm run build:uat | UAT | TypeScript 检查和 UAT 环境构建 |
npm run build:pre | 预生产 | TypeScript 检查和预生产构建 |
npm run preview | 预览 | 本地预览生产构建 |
npm run clean | 清理 | 删除生成的文件和缓存 |
开发服务器
开发服务器由 Vite 驱动，配置为提供最佳的开发体验：
- 热模块替换 (HMR)：无需完整页面重载即可即时更新
- TypeScript 支持：实时类型检查
- 代理配置：无缝 API 集成
- Source Maps：增强的调试体验
- 开发工具集成：用于低代码开发的内置 VTJ 开发工具
vite.config.ts 文件使用 VTJ 的 CLI 配置辅助程序 createViteConfig()，它应用合理的默认值，同时允许自定义：
import { createViteConfig } from "@vtj/cli";
import { createDevTools } from "@vtj/local";
import proxy from "./proxy.config";
export default createViteConfig({
proxy,
plugins: [createDevTools()],
});
createDevTools()插件在浏览器中启用 VTJ 的低代码开发工具，允许你在视觉上设计页面，同时保持对生成代码的完全控制。这是连接视觉设计和基于代码开发的关键功能。
架构概述
了解 VTJ Web 应用程序的架构对于有效开发和自定义至关重要。该架构采用分层方法，分离关注点同时保持灵活性。
flowchart TD
subgraph Presentation Layer
A[XMask 布局] --> B[Vue 组件]
B --> C[视图/页面]
end
subgraph VTJ Core Layer
D[Provider] --> E[服务层]
E --> F[渲染器]
F --> G[引擎]
end
subgraph Integration Layer
H[适配器] --> I[Vue Router]
H --> J[Pinia]
H --> K[Vue I18n]
L[图标插件] --> H
M[开发工具] --> H
end
subgraph Framework Layer
N[Vue 3]
end
C --> D
G --> N
I --> N
J --> N
K --> N
该架构展示了 VTJ 如何与 Vue 生态系统无缝集成，同时提供强大的低代码能力。Provider 作为中央枢纽，通过适配器模式将 VTJ 引擎、渲染器和服务与 Vue 组件连接起来。
核心依赖
Web 应用程序模板包含精心选择的依赖项，提供了坚实的基础：
| 依赖 | 版本 | 用途 |
|---|---|---|
@vtj/web | latest | 核心 VTJ Web 平台集成 |
@vtj/pro | latest | VTJ 专业功能 (开发依赖) |
@vtj/cli | latest | 构建工具和配置 |
vue | ~3.5.0 | 核心响应式框架 |
vue-router | ~4.6.0 | 客户端路由 |
pinia | ~3.0.2 | 状态管理 |
vue-i18n | ~11.2.2 | 国际化 |
这些依赖项由 VTJ 团队维护并经过共同测试，以确保兼容性和稳定性。
高级功能和自定义
虽然默认模板提供了即时的生产力，但 VTJ 支持广泛的自定义以满足特定的项目需求。该架构设计灵活，且不损害可维护性。
路由配置
路由器预配置了哈希模式以实现最大兼容性，并包含常见场景的默认路由：
import { createRouter, createWebHashHistory } from "vue-router";
const router = createRouter({
history: createWebHashHistory(),
routes: [
{
path: "/unauthorized",
name: "Unauthorized",
component: () => import("@/views/unauthorized.vue"),
},
{
path: "/:pathMatch(.*)*",
name: "NotFound",
component: () => import("@/views/not-found.vue"),
},
],
});
你可以通过添加应用程序路由来扩展此配置，启用延迟加载以提高性能，以及实现导航守卫以进行身份验证和授权。
自定义布局
App.vue 中的 XMask 组件提供了一个具有可配置属性的综合布局系统：
| 属性 | 类型 | 描述 | 默认值 |
|---|---|---|---|
title | string | 应用程序标题 | - |
logo | string | 自定义 Logo URL | 默认 VTJ logo |
menus | array | 导航菜单项 | - |
disabled | boolean | 禁用布局功能 | false |
pure | boolean | 无标题栏的纯净模式 | false |
themeSwitchable | boolean | 启用主题切换 | - |
可以通过修改 actions 数组来自定义操作栏，以包含用于应用程序特定操作的图标、标签和处理程序。
特定环境构建
VTJ 通过 ENV_TYPE 环境变量支持多种构建环境。这为开发、测试和生产启用了不同的配置：
# SIT 环境构建
npm run build:sit
# UAT 环境构建
npm run build:uat
# 生产构建
npm run build
每个构建环境可以通过相应的环境 JSON 文件控制不同的 API 端点、功能标志和优化设置。
常见问题排查
开始使用 VTJ Web 应用程序时，你可能会遇到一些常见问题。以下是针对频繁报告的问题的解决方案：
Node 版本兼容性
VTJ 需要 Node.js 版本 20 或更高版本。如果遇到与版本相关的错误，请确保你使用的是兼容的 Node 版本：
node --version # 应为 v20.x.x 或更高版本
如果需要，使用 nvm（Node 版本管理器）安装并切换到正确的版本：
nvm install 20
nvm use 20
依赖安装问题
如果依赖安装失败，请尝试使用 setup 脚本中指定的中国 npm 镜像：
npm install --unsafe-perm --registry=https://registry.npmmirror.com
端口冲突
如果默认开发服务器端口被占用，你可以在 Vite 配置中指定不同的端口或使用 --port 标志：
npm run dev -- --port 3001
构建错误
TypeScript 构建错误通常可以通过确保安装了所有依赖项来解决，并以严格模式运行 TypeScript 以获得更好的类型安全性。构建过程包含 vue-tsc 以进行全面的类型检查。
后续步骤
既然你已经成功创建了 VTJ Web 应用程序，你可以探索更多高级主题以最大化你的生产力：
- 架构概述：深入了解 VTJ 的架构和系统设计，了解低代码引擎、渲染器和代码生成器如何协同工作。
- 项目结构：了解完整的项目结构和文件组织，以便更好地管理不断增长的应用程序。
- DSL 架构：了解驱动 VTJ 视觉设计器和代码生成能力的 DSL 架构和数据模型。
- 物料开发：按照自定义物料组件指南创建自定义组件和物料。
- 插件系统：使用插件系统开发文档开发自定义插件来扩展 VTJ 的功能。
- API 参考：查阅完整的引擎 API 参考，获取有关可用 API 及其用法的详细信息。
对于移动端 Web 应用程序，请参阅创建 H5 移动应用程序。如果你需要跨平台移动开发能力，请查看创建 UniApp 应用程序（如果可用）。
