AI 驱动的 Vue3 应用开发平台 入门指南（三）：安装与环境配置

安装与环境配置本指南将引导你完成 VTJ 的安装和开发环境搭建。VTJ 提供两种安装路径一种是使用官方脚手架 CLI 创建新项目以进行生产开发另一种是克隆仓库以参与核心引擎贡献和扩展平台。系统要求VTJ 采用前沿的 Web 技术构建对 Node.js 版本和包管理器配置有特定要求。要求项最低版本推荐版本备注Node.jsv20.0.0v20.x LTSES2022 特性和模块支持所必需pnpm8.x10.13.0Monorepo 包管理lerna8.x8.2.0多包仓库管理TypeScript5.x5.9.0类型安全和 IDE 支持安装方法概述VTJ 根据你的使用场景提供了灵活的安装方式。下面的决策流程图可以帮助你选择合适的路径方法一创建新项目推荐用于应用开发对于大多数构建生产应用的开发者来说使用官方脚手架 CLI 是最快上手的方式。create-vtj工具会生成针对不同平台优化的预配置项目模板。第一步使用 CLI 创建项目CLI 支持多种项目类型。请选择与你目标平台匹配的模板npm create vtjlatest --registryhttps://registry.npmmirror.com -- -t app # H5 移动应用 npm create vtjlatest --registryhttps://registry.npmmirror.com -- -t h5 # uni-app 跨平台微信、H5、App npm create vtjlatest --registryhttps://registry.npmmirror.com -- -t uniapp # 物料/组件开发项目 npm create vtjlatest --registryhttps://registry.npmmirror.com -- -t materialCLI 内部会从 create-vtj/templates 复制模板文件并配置相应的依赖和构建设置。第二步进入目录并安装依赖项目创建完成后进入你的项目目录并安装依赖cd vtj-project npm install # 或者如果有可用的设置脚本 npm run setup设置脚本使用中国 npm 镜像以加快下载速度registryhttps://registry.npmmirror.com。第三步启动开发服务器启动开发环境npm run dev开发服务器启动时会启用热重载功能。对于 Web 应用这通常会运行集成了 VTJ 开发工具插件的 Vite。方法二克隆仓库面向贡献者和引擎定制对于希望为 VTJ 核心引擎做贡献、深度定制低代码引擎或参与平台本身开发的开发者克隆仓库是必要步骤。第一步安装全局依赖首先请确保你已全局安装所需的包管理器npm install -g lernalatest pnpmlatest --registryhttps://registry.npmmirror.com第二步克隆仓库从 Gitee 克隆官方仓库git clone https://gitee.com/newgateway/vtj.git cd vtj第三步安装依赖并构建该仓库使用由 pnpm workspaces 管理的 monorepo 结构。运行设置脚本以安装所有包的依赖npm run setup此命令会在所有工作空间包中执行pnpm install --unsafe-perm --registryhttps://registry.npmmirror.com。安装完成后构建所有包npm run build构建过程使用 lerna 在所有非私有包中执行构建脚本。第四步启动开发环境启动 VTJ 平台本身的开发服务器npm run dev这将启动位于 dev 目录中的开发环境其中包含完整的 VTJ 设计器、渲染器和示例应用。可用项目模板create-vtjCLI 提供了几个针对不同用例定制的预配置模板。模板选择系统会以交互方式提示你或接受命令行标志。模板名称显示名称使用场景关键技术appWeb应用PC/桌面端 Web 应用Vue3, Vite, Element Plus, vtj/webh5H5应用移动端 Web 应用Vue3, Vite, vtj/h5, 移动端优化uniapp移动端应用跨平台微信、H5、Appdcloudio/uni-app, vtj/uni-appmaterial物料开发项目自定义组件库开发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,liveNODE_ENVNode 运行时环境development,productionExtension构建扩展标志true/false构建脚本和常用命令每个 VTJ 项目都包含用于常见操作的标准 npm 脚本命令描述使用时机npm run setup使用 npm 镜像安装依赖初始项目设置npm run dev启动开发服务器主动开发时npm run build生产构建部署到生产环境npm run build:sitSIT 环境构建预发布部署npm run build:uatUAT 环境构建用户验收测试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-vtjCLI 报告模板名称无效请在 create-vtj/src/options.ts 中验证可用模板。可用模板包括app、h5、uniapp、material、plugin、extension和library。后续步骤完成安装后你就可以开始使用 VTJ 进行构建了。根据你的安装方法和项目类型请继续阅读对于创建 Web 应用创建 Web 应用 - 了解如何构建 PC 应用对于创建 H5 移动应用创建 H5 移动应用 - 移动端特定开发模式对于理解 VTJ 架构架构概览 - 深入了解 VTJ 的引擎、渲染器和代码生成系统对于使用 DSLDSL 模式和数据模型 - 理解 VTJ 的声明式语言对于自定义组件创建自定义物料组件 - 使用你自己的组件扩展 VTJ参考资料开源代码仓库 https://vtj.pro/