ToolJet 版本控制（Version Control）实战指南：多版本管理、环境隔离与发布回滚-育师

ToolJet 版本控制（Version Control）实战指南：多版本管理、环境隔离与发布回滚

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

ToolJet 的版本控制（Version Control）功能让每个应用都能维护多个独立版本，支持迭代式开发与系统性发布更新。通过 App Version Manager 即可完成版本的创建、重命名、删除与切换，配合多环境（Development / Staging / Production）与发布、回滚机制，实现“新功能在隔离版本中实验，测试通过后再发布上线”的稳定交付流程。读完本文，你将掌握 ToolJet 应用版本管理的完整操作路径，并理解其前后端实现原理与安全限制。

版本控制解决什么问题

在 ToolJet 中，应用本质上是一份由页面、组件、数据查询与事件处理器组成的定义（definition）。版本控制围绕这份定义提供以下能力：

多版本并存：每个版本彼此隔离，可独立演进，互不影响；
迭代开发：在某个版本上实验新功能，不干扰已发布版本；
受控发布：版本在充分测试后再发布给最终用户，降低线上风险；
快速回滚：发布出现问题时可随时切回先前稳定版本（详见发布与回滚指南）；
环境绑定：版本可对应不同环境（开发、预发布、生产），关于多环境的概念与配置，参见多环境指南。

例如，想实验一个新特性时，可以基于当前版本创建一个新版本进行开发调试；通过充分测试后，再将该版本发布上线。整个过程中已发布的版本始终可用，最大程度减少停机时间。

版本在前后端的数据模型

从源码结构看，版本由服务端的app_versions表承载，核心实体AppVersion记录name、definition、status、currentEnvironmentId、parentVersionId、versionType、branchId等字段。前端通过 App Builder 中的版本管理器与之交互，关键的几个实现文件如下：

前端版本管理器 UI：AppVersionsManager.jsx 与 VersionManagerDropdown.jsx；
创建版本弹窗：CreateVersionModal.jsx；
重命名版本弹窗：EditVersionModal.jsx；
服务端版本操作（创建 / 删除 / 守卫校验）：server/src/modules/versions/util.service.ts；
服务端发布动作（写入currentVersionId）：server/src/modules/apps/service.ts。

创建版本（Creating a Version）

版本创建入口位于编辑器顶部的App Version Manager（应用版本管理器）。它显示应用当前版本，并支持在不同版本之间切换。

操作步骤如下：

从工具栏进入App Version Manager并点击下拉框，会列出应用的全部可用版本。已发布（released）的版本名以绿色显示。
点击下拉列表底部的Create new version按钮，弹出创建版本弹窗。
输入Version Name（版本名称）。
在Create version from（从哪个版本创建）下拉框中选择新版本的基底版本；若不做选择，ToolJet 会自动使用最后创建的版本。
点击Create new version按钮完成创建。

创建弹窗的交互界面如下图所示：

版本名称的校验规则

从 CreateVersionModal.jsx 的createVersion实现可以看到，创建时会执行多层校验：

版本名称不能为空；
版本名称长度不能超过 25 个字符；
版本名称不能包含空格或特殊字符，被禁用的字符集为` ~ ^ : ? * [ \ @ {；
版本描述（description）长度不能超过 500 个字符；
版本名称必须唯一，若服务端返回唯一约束冲突（错误码23505），界面会提示“Version name already exists”。

此外，对于开启了 Git Sync 的工作区，前端会先调用gitSyncService.checkTagExists检查同名 Git tag 是否已存在，避免与远端仓库的 tag 冲突；保存动作本身由服务端一次性完成（数据库写入 + Git tag 创建）。

版本一旦保存即被锁定

创建弹窗底部有一行明确的提示：“Saving the version will lock it. To make any edits afterwards, you'll need to create a draft version.”也就是说，版本保存后即成为不可编辑的已发布快照，后续修改需要基于它创建 draft（草稿）版本。在开启 Git Sync 的工作区，版本名称与描述在保存后同样不可再修改。

切换版本

在下拉列表中选择某个版本即可切换编辑器上下文。在 AppVersionsManager.jsx 的selectVersion中，切换当前版本后：

会调用changeEditorVersionAction(appId, id, ...)加载该版本的完整定义；
在 Viewer（预览 / 分享）模式下，会同步更新 URL 中的version查询参数，使用户可以直达指定版本；
若选择的就是当前正在编辑的版本，会提示“You are already editing this version”。

版本列表采用懒加载：下拉菜单打开时才调用lazyLoadAppVersions(appId)拉取全部版本，避免应用加载时阻塞。

重命名版本（Renaming a Version）

如需修改某个版本的名称，操作路径为：

打开顶部的App Version Manager；
在版本下拉列表中找到目标版本；
点击版本名称旁的重命名图标（铅笔样式）；
在弹出的弹窗中修改版本名称，保存即可。

重命名弹窗界面如下：

从 EditVersionModal.jsx 的实现看，重命名同样受25 个字符上限与唯一性约束（"Version name must be unique and max 25 characters"）。另外需要注意：重命名属于对版本的编辑操作，仅在Development（开发）环境中允许——参考多环境权限表，Staging 与 Production 环境中不可重命名版本。

删除版本（Deleting a Version）

删除版本同样在App Version Manager中操作：

打开版本下拉列表；
定位到目标版本；
点击版本右侧的删除图标；
在确认弹窗中确认删除。

关键限制：已发布（released）的版本不可删除。删除确认弹窗如下图所示：

服务端的删除守卫

前端 UI 对已发布版本隐藏删除图标，但这只是第一层防护。服务端 util.service.ts 的deleteVersion方法实现了一整套删除守卫，从源码看包括：

已发布版本不可删：若app.currentVersionId === versionId或版本状态为RELEASED，抛出You cannot delete a released version；
唯一版本不可删：若该应用 / 模块只剩这一个版本，抛出Cannot delete only version of ...；
Git 功能分支版本不可删：开启 Git Sync 后，feature branch 上的版本不能从此入口删除；
最后一个草稿不可删：Git Sync 开启时，若删除的是唯一的草稿版本，会抛出Cannot delete the last draft version ... while git sync is enabled；
被引用的模块版本不可删：若删除的是模块（module）版本且该版本正被一个或多个应用中的ModuleViewer组件使用，会通过checkModuleVersionInUse检测并抛出Cannot delete this version. Used by: <应用列表>，前端随后弹出“Dependent apps found!”提示。

删除版本时还会同步清理该版本关联的查询文件夹数据（cleanupQueryFolderData），并走事务（dbTransactionWrap）保证一致性。

版本与环境的协作：发布与回滚

版本控制并非孤立功能，它与 ToolJet 的多环境模型深度绑定。默认每个应用都有Development（开发）、Staging（预发布）、Production（生产）三个环境，各环境对版本的操作权限不同：

操作	Development	Staging	Production
编辑版本	✅	❌	❌
重命名版本	✅	❌	❌
删除版本	✅	❌	❌
创建新版本	✅	❌	❌
提升（Promote）	✅	✅	-

典型生命周期为：开发者在Development中构建并保存版本 → 将版本Promote到Staging供测试团队验证（Staging 中应用与查询不可编辑）→ 测试通过后 Promote 到Production→ 点击Release按钮正式发布给最终用户。

发布（Release）背后的实现

发布动作将选中的版本设置为应用的当前版本。从 server/src/modules/apps/service.ts 的发布逻辑看：

服务端会校验目标版本的 slug 是否与其他已发布应用冲突（Cannot release — slug conflicts with another released app.）；
校验通过后执行manager.update(App, appId, { currentVersionId: versionToBeReleased })，将应用的current_version_id指向被发布版本；
同时写入APP_RELEASE审计日志，记录 released version、环境名称等元数据。

发布后，该版本便成为终端用户访问到的版本（关于应用的多种分享方式，见分享应用指南），同时该版本在下拉列表中显示为绿色、且不可被删除。