安装与环境配置

本指南将引导你完成 VTJ 的安装和开发环境搭建。VTJ 提供两种安装路径：一种是使用官方脚手架 CLI 创建新项目以进行生产开发，另一种是克隆仓库以参与核心引擎贡献和扩展平台。

系统要求

VTJ 采用前沿的 Web 技术构建，对 Node.js 版本和包管理器配置有特定要求。

要求项	最低版本	推荐版本	备注
Node.js	v20.0.0+	v20.x LTS	ES2022+ 特性和模块支持所必需
pnpm	8.x+	10.13.0+	Monorepo 包管理
lerna	8.x+	8.2.0+	多包仓库管理
TypeScript	5.x+	5.9.0+	类型安全和 IDE 支持

安装方法概述

VTJ 根据你的使用场景提供了灵活的安装方式。下面的决策流程图可以帮助你选择合适的路径：

方法一：创建新项目（推荐用于应用开发）

对于大多数构建生产应用的开发者来说，使用官方脚手架 CLI 是最快上手的方式。create-vtj 工具会生成针对不同平台优化的预配置项目模板。

第一步：使用 CLI 创建项目

CLI 支持多种项目类型。请选择与你目标平台匹配的模板：

npm create vtj@latest --registry=https://registry.npmmirror.com -- -t app

# H5 移动应用
npm create vtj@latest --registry=https://registry.npmmirror.com -- -t h5

# uni-app 跨平台（微信、H5、App）
npm create vtj@latest --registry=https://registry.npmmirror.com -- -t uniapp

# 物料/组件开发项目
npm create vtj@latest --registry=https://registry.npmmirror.com -- -t material

CLI 内部会从 create-vtj/templates 复制模板文件，并配置相应的依赖和构建设置。

第二步：进入目录并安装依赖

项目创建完成后，进入你的项目目录并安装依赖：

cd vtj-project
npm install
# 或者如果有可用的设置脚本
npm run setup

设置脚本使用中国 npm 镜像以加快下载速度：registry=https://registry.npmmirror.com。

第三步：启动开发服务器

启动开发环境：

npm run dev

开发服务器启动时会启用热重载功能。对于 Web 应用，这通常会运行集成了 VTJ 开发工具插件的 Vite。

方法二：克隆仓库（面向贡献者和引擎定制）

对于希望为 VTJ 核心引擎做贡献、深度定制低代码引擎或参与平台本身开发的开发者，克隆仓库是必要步骤。

第一步：安装全局依赖

首先，请确保你已全局安装所需的包管理器：

npm install -g lerna@latest pnpm@latest --registry=https://registry.npmmirror.com

第二步：克隆仓库

从 Gitee 克隆官方仓库：

git clone https://gitee.com/newgateway/vtj.git
cd vtj

第三步：安装依赖并构建

该仓库使用由 pnpm workspaces 管理的 monorepo 结构。运行设置脚本以安装所有包的依赖：

npm run setup

此命令会在所有工作空间包中执行 pnpm install --unsafe-perm --registry=https://registry.npmmirror.com。

安装完成后，构建所有包：

npm run build

构建过程使用 lerna 在所有非私有包中执行构建脚本。

第四步：启动开发环境

启动 VTJ 平台本身的开发服务器：

npm run dev

这将启动位于 dev 目录中的开发环境，其中包含完整的 VTJ 设计器、渲染器和示例应用。

可用项目模板

create-vtj CLI 提供了几个针对不同用例定制的预配置模板。模板选择系统会以交互方式提示你，或接受命令行标志。

模板名称	显示名称	使用场景	关键技术
app	Web应用	PC/桌面端 Web 应用	Vue3, Vite, Element Plus, @vtj/web
h5	H5应用	移动端 Web 应用	Vue3, Vite, @vtj/h5, 移动端优化
uniapp	移动端应用	跨平台（微信、H5、App）	@dcloudio/uni-app, @vtj/uni-app
material	物料开发项目	自定义组件库开发	@vtj/materials, 测试基础设施
plugin	低代码区块插件	区块/插件开发	@vtj/plugin, 可扩展架构
extension	设计器扩展开发项目	设计器扩展开发	@vtj/extension, 自定义面板
library	通用类库	可复用工具库开发	TypeScript, Vitest

项目结构概览

当你使用 create-vtj 创建项目时，生成的结构遵循针对 VTJ 开发优化的标准化布局：

关键配置文件

package.json - 包含项目元数据、依赖和构建脚本。包括 VTJ 特定的包，如 @vtj/web、@vtj/pro 和 @vtj/cli。

vite.config.ts - 包含 VTJ 特定插件和代理设置的 Vite 构建配置：

import { createViteConfig } from "@vtj/cli";
import { createDevTools } from "@vtj/local";
import proxy from "./proxy.config";

export default createViteConfig({
  proxy,
  plugins: [createDevTools()],
});

tsconfig.json - 继承 VTJ 基础配置并包含自定义路径别名的 TypeScript 配置：

{
  "extends": "./node_modules/@vtj/cli/config/tsconfig.web.json",
  "compilerOptions": {
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "paths": {
      "@/*": ["./src/*"],
      "$vtj/*": ["./.vtj/*"]
    }
  }
}

env.json - 针对不同部署阶段（本地、SIT、UAT、生产）的环境特定配置。

proxy.config.ts - 用于后端集成的开发服务器 API 代理配置。

Monorepo 工作空间结构

VTJ 仓库本身是一个由 pnpm workspaces 管理的 monorepo，包含多个相互依赖的包：

packages:
  - "packages/*" # 核心包 (@vtj/core, @vtj/renderer 等)
  - "platforms/*" # 特定平台构建
  - "apps/*" # 示例应用
  - "create-vtj" # 脚手架 CLI
  - "dev" # 开发环境
  - "docs" # 文档

环境变量

VTJ 项目使用环境变量来配置不同阶段：

变量	描述	示例
ENV_TYPE	部署环境	local, sit, uat, live
NODE_ENV	Node 运行时环境	development, production
Extension	构建扩展标志	true/false

构建脚本和常用命令

每个 VTJ 项目都包含用于常见操作的标准 npm 脚本：

命令	描述	使用时机
npm run setup	使用 npm 镜像安装依赖	初始项目设置
npm run dev	启动开发服务器	主动开发时
npm run build	生产构建	部署到生产环境
npm run build:sit	SIT 环境构建	预发布部署
npm run build:uat	UAT 环境构建	用户验收测试
npm run preview	本地预览生产构建	测试构建输出
npm run clean	清理构建产物和依赖	重置项目状态

故障排除

在安装之前，请确保你的 Node.js 版本满足最低要求（v20.0.0+）。VTJ 使用了早期 Node 版本不支持的 ES2022+ 特性。如果需要，请使用 nvm use 20 切换到兼容版本。

依赖安装问题

如果遇到依赖冲突或安装失败：

# 清理所有 node_modules 和 lock 文件
npm run clean

# 重新安装依赖
npm run setup

清理脚本会删除所有工作空间包中的 node_modules、dist、lib 和 lock 文件。

构建错误

对于仓库中的 TypeScript 或构建错误：

# 清理并重新构建
npm run clean
npm run setup
npm run build

找不到模板

如果 create-vtj CLI 报告模板名称无效，请在 create-vtj/src/options.ts 中验证可用模板。可用模板包括：app、h5、uniapp、material、plugin、extension 和 library。

后续步骤

完成安装后，你就可以开始使用 VTJ 进行构建了。根据你的安装方法和项目类型，请继续阅读：

• 对于创建 Web 应用：创建 Web 应用 - 了解如何构建 PC 应用
• 对于创建 H5 移动应用：创建 H5 移动应用 - 移动端特定开发模式
• 对于理解 VTJ 架构：架构概览 - 深入了解 VTJ 的引擎、渲染器和代码生成系统
• 对于使用 DSL：DSL 模式和数据模型 - 理解 VTJ 的声明式语言
• 对于自定义组件：创建自定义物料组件 - 使用你自己的组件扩展 VTJ

参考资料：

开源代码仓库 https://vtj.pro/