VTJ.PRO 在线应用开发平台的构建与发布脚本

构建与发布脚本

本文档详细介绍了位于 scripts/ 目录下的自动化脚本。这些工具用于管理 VTJ.PRO 平台的整个生命周期，包括项目模板打包、环境清理，以及为"完整版"和"云版"两种部署变体生成可用于生产的发布产物。

发布变体：完整版 vs. 云版

构建系统区分了两种主要的发行类型，以适应不同的部署场景。两种变体都会被打包成ZIP压缩包，存放在 _releases 目录下，该目录已被版本控制系统排除。

变体	用途	主要特征
完整版 (`vtj-pro-full`)	自托管、离线或独立部署	包含所有源代码、后端服务、前端资源及本地依赖。
云版 (`vtj-pro-cloud`)	托管式或云原生部署	针对特定基础设施（如 OSS 或共享服务）由外部管理的环境进行了优化。

脚本: publish.mjs

publish.mjs 脚本是主要的发布包生成器。它负责从单体仓库中收集文件，应用排除规则移除开发工件，并将结果压缩成带版本号的ZIP文件。

实现细节

该脚本使用 archiver 进行压缩，使用 fs-extra 进行文件系统操作。它定义了一组全局排除规则，以确保发布的产物轻量且安全。

关键排除规则： 打包过程中会忽略以下模式：

开发元数据: .git, .vscode, .idea, .history
构建产物: node_modules, dist (生产环境的前端/后端输出除外), _releases
临时文件: *.log, package-lock.json, pnpm-lock.yaml
环境特定文件: .env.local, .DS_Store

发布工作流逻辑

脚本遵循线性执行路径来构建发布包：

版本解析 ：从根目录的 package.json 中读取当前版本。
目录准备 ：确保 _releases 目录存在。
归档初始化 ：为目标ZIP文件（例如 vtj-pro-full-v1.0.0.zip）创建一个写入流。
文件聚合 ：递归遍历目录树，应用 ignore 过滤器跳过仅用于开发的文件。

发布流程

下图展示了从单体仓库源代码到最终发布产物的数据流。

发布打包架构

flowchart subgraph Source Workspace ROOT[Root Directory] FE["/frontend/dist"] BE["/backend/dist"] TMPL["/templates"] DOCS["/_docs"] end subgraph publish.mjs Logic FILTER["ignore() filter"] ARCHIVE["archiver (zip)"] end subgraph Output FULL[_releases/vtj-pro-full-vX.zip] CLOUD[_releases/vtj-pro-cloud-vX.zip] end ROOT --> FILTER FE --> FILTER BE --> FILTER TMPL --> FILTER DOCS --> FILTER FILTER -- "Exclude .git, node_modules, etc." --> ARCHIVE ARCHIVE --> FULL ARCHIVE --> CLOUD

脚本: template.mjs

template.mjs 脚本负责打包位于 templates/ 目录下的入门项目模板（Web、H5 和 UniApp）。这些模板对于低代码引擎初始化新用户项目至关重要。

实现与数据流

该脚本执行两个主要功能：

内部同步 ：打包模板并将其放置到 backend/zip/ 目录下。这使得 NestJS 后端可以在项目创建过程中通过 TemplateModule 提供这些模板。
外部发布 ：将模板打包到根目录下的 zip/ 目录中，用于手动分发或 CLI 工具使用。

模板打包流程

flowchart subgraph Template Sources T1["/templates/web"] T2["/templates/h5"] T3["/templates/uniapp"] end subgraph template.mjs ZIP_EXEC["zipTask(name, source)"] end subgraph Destinations BE_ZIP["/backend/zip/*.zip"] ROOT_ZIP["/zip/*.zi"p] end T1 --> ZIP_EXEC T2 --> ZIP_EXEC T3 --> ZIP_EXEC ZIP_EXEC --> BE_ZIP ZIP_EXEC --> ROOT_ZIP

脚本: clean.mjs

clean.mjs 脚本提供了一个用于重置开发环境的实用工具。它的目标是那些在构建和执行过程中经常被填充但不应持久存在的目录。

目标目录

该脚本会以编程方式删除以下路径：

node_modules/：根目录及各个包的依赖。
dist/：前端和后端的编译输出。
_releases/：先前生成的发布包。
uploadfiles/：上传资产的临时或本地存储。

配置与环境

这些脚本依赖于项目的工作区配置，以便在不同的环境中正确运行。

工作区依赖提升

该项目使用 pnpm，并通过 .npmrc 文件定义了特定的依赖提升规则，以确保构建脚本能够访问必要的依赖项（如 archiver 或 fs-extra），而无需在每个子包中都安装它们。

配置项	值	用途
`hoist`	`true`	启用依赖提升，将依赖提升到根目录的 `node_modules`。
`node-linker`	`hoisted`	使用扁平的 `node_modules` 结构，以兼容标准的 Node.js 脚本。
`registry`	`https://registry.npmmirror.com`	配置镜像源，以加快构建过程中的依赖解析速度。

参考资料

官网文档：vtj.pro/
在线平台：app.vtj.pro/
开源仓库：gitee.com/newgateway/...