ToolJet 3.0 Cloud Migration Guide升级前必读的破坏性变更检查清单与实战迁移方案【免费下载链接】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 官方《ToolJet 3.0 Cloud Migration Guide》为主体系统梳理 3.0 版本升级涉及的动态输入限制、组件与查询命名冲突、属性面板变量访问规则、多页面组件命名、已弃用功能移除以及响应头元数据等破坏性变更并结合当前仓库的源码实现与配套迁移文档给出可落地的操作步骤。读完本文你将能够对照清单逐项审查既有应用、定位高风险引用模式并在升级前后完成组件/查询/数据源/变量的规范化迁移与回归验证。升级背景与时间线ToolJet Cloud 将于2024 年 11 月 11 日自动升级至 3.0 版本。这次升级属于major version升级包含多项破坏性变更breaking changes可能影响现有应用的正常运行。:::warning 重要提示 升级是自动进行且无法推迟的。所有应用的改造工作必须在 11 月 11 日之前完成否则应用可能中断甚至崩溃。 :::在动手改造前建议先完成以下准备工作自托管场景同样适用参见同仓库的 自托管升级指南数据库备份对业务数据库做完整备份应用清单审查逐项核对本文列出的破坏性变更与已弃用功能测试环境先行先在测试环境完成升级演练再处理生产应用。动态输入限制Dynamic Input Restrictions3.0 起不能再动态改变对组件名称的引用。即无法通过变量、表达式拼接或间接取值的方式构造组件名。需执行的操作审查应用中所有动态组件名引用并视情况进行重构将动态组件引用全部替换为静态引用修改完成后逐一测试所有组件间的交互行为。不再支持的写法以下三种动态引用模式在 3.0 中均不再生效// 1. 用变量构造组件名 —— 不再生效 {{components[variables.componentNameVariable].value}} // 2. 动态拼接组件名 —— 不受支持 {{components[textinput components.tabs1.currentTab].value}} // 3. 动态访问嵌套属性 —— 不允许 {{components.table1[components.textinput1.value]}}推荐替代写法静态引用{{components.textinput1.value}} {{components.table1.selectedRow}} {{queries.query1.data}}迁移要点如果业务上确实需要按条件切换组件应改为显式静态地列出所有候选组件引用再通过条件表达式如三元运算在引用结果上做选择而不是在引用路径上做拼接。组件与查询命名冲突Component and Query Naming:::note 该问题仅在升级过程中存在。应用在 ToolJet 3.0 上运行后组件与查询可以使用完全相同的名称不会产生任何问题。 :::需执行的操作审查应用中是否存在查询与组件同名的情况临时重命名组件或查询确保名称唯一记录所有被重命名的组件/查询以便升级后视情况还原重命名后测试受影响的组件与查询。原因与示例升级时若组件引用了同名的查询该映射关系可能在升级过程中被破坏。原因在于ToolJet 旧版本对组件和查询共用一套全局 ID 到名称的映射表而 3.0 将这套映射拆分为组件、查询各自独立的映射。典型场景名为userData的表格组件引用了同样名为userData的查询升级过程中该引用可能断裂。建议策略升级前将同名的一方临时重命名例如查询改为userData_query并完整记录改名映射升级完成并验证无误后再按记录恢复原名。属性面板中的变量访问逻辑Property Panel Logic3.0 对属性面板中变量存在性检查的写法提出了新规则旧式探测写法将不再受支持。需执行的操作审查属性面板中所有的变量检查逻辑将既有变量存在性检查更新为新版推荐格式移除所有不受支持的逻辑模式更新后测试所有使用变量检查的组件。新的变量访问规则对于components / queries / page 变量在component/query/page关键字之后必须至少存在两个键对于variables在variables关键字之后至少应存在一个键。受支持的格式components.textinput1.value components?.textinput1?.value components[textinput1].value queries.restapi1.data page.variables.name variables[name] variables.name不再支持的格式{{name in variables}} {{Object.keys(variables).includes(name)}} {{variables.hasOwnProperty(name)}}推荐的存在性检查方式{{variables[name] ?? false}}:::caution 这些变更可能影响应用与变量、组件的交互方式。更新完成后务必进行全面测试。 :::多页面应用的组件命名Multi-Page Component Names需执行的操作审查多页面应用中是否存在跨页面同名的组件方案 A重命名组件确保跨页面全局唯一方案 B修改查询改用查询参数query parameters而非直接引用组件记录所有组件名变更测试受影响页面及其相互交互。当前限制与细节当同名组件出现在多个页面并与查询关联时该查询只在组件最初被关联的那个页面上正常工作。典型场景page1和page2中各有一个名为textinput1的组件在page1创建了一条关联textinput1的查询该查询仅在page1上正常工作切换到page2时即使那里存在同名组件查询也不会按预期工作。:::tip 构建多页面应用时建议在所有页面中使用唯一的组件名称以避免查询绑定出现潜在问题。 :::后续规划官方将在后续版本中增加跨页面强制组件名称唯一的功能。在此之前建议通过团队命名规范如按页面前缀命名组件page1_textinput1提前规避。已弃用功能的移除Removal of Deprecated Features旧版 Kanban Board 组件旧版已弃用的Kanban Board组件将彻底停止工作。升级后若未处理使用该组件的应用将直接崩溃。必需操作立即识别应用中所有旧版Kanban Board组件使用新版Kanban组件创建新的看板将数据与配置迁移到新组件移除所有旧版 Kanban Board 组件更新所有连接到旧看板的查询或工作流全面测试确保原有功能完整保留。:::caution 11 月 11 日之后包含旧版 Kanban Board 组件的应用将崩溃且无法使用。 :::本地数据源Local Data Sources自 ToolJet 3.0.0 起本地数据源Local Data Sources已被完全停用更早版本中已弃用3.0 彻底移除支持。升级前操作识别应用中所有的本地数据源将其迁移为全局工作区数据源global workspace data sources更新所有使用这些数据源的查询与组件迁移后测试所有受影响的组件与查询。升级后补救如果升级前未完成迁移查询将显示本地数据源不再受支持的错误提示。具体补救步骤参见 本地数据源迁移指南定位报错查询进入应用 → 展开查询管理器Query Manager→ 找到显示本地数据源错误的查询该查询只会显示错误信息其余内容被隐藏创建新数据源进入Data Sources区域创建同类型的新数据源例如原 PostgreSQL 本地数据源 → 新建 PostgreSQL 数据源填写正确配置并保存重新连接查询回到应用打开报错查询在Source字段的下拉框中选择新建的同类型数据源查询即恢复连接测试查询逐个运行更新后的查询确认一切符合预期。工作区变量Workspace Variables升级前操作识别所有使用工作区变量的场景将其替换为工作区常量Workspace Constants更新所有使用这些变量的组件与查询为新常量配置合适的基于角色的访问权限迁移后测试所有受影响功能。为什么迁移到工作区常量工作区常量仅在服务端解析客户端无法接触安全性更高同时可按角色为用户分配对工作区常量的创建、更新、删除权限。这一点在源码中也有印证——服务端数据源工具服务在解析数据源选项时专门处理workspace_constant字段并写入凭据服务参见 server/src/modules/data-sources/util.service.ts且禁止在默认master分支上直接添加工作区常量同文件 util.service.ts加密字段中的常量必须走 PR 工作流。完整的迁移路径参见 工作区变量迁移指南按照 创建工作区常量 的步骤为每个变量值创建对应的常量将应用/数据源中的工作区变量替换为对应的常量全部迁移并充分测试后到Workspace Settings → Workspace Variables标签页中删除旧的工作区变量。响应头与元数据Response Headers and Metadata需执行的操作识别所有访问响应头response headers的位置更新代码使用新的metadata格式迁移后测试所有受影响的查询与组件。变更说明ToolJet 3.0 为所有数据源引入了通过metadata暴露附加信息的能力。此前该能力仅对REST API与GraphQL数据源可用。变更前旧写法{{queries.queryName.responseHeaders}}变更后新写法{{queries.queryName.metadata}}metadata对象包含请求与响应的详细信息请求 URL、请求方法、请求头、请求参数、响应状态码与响应头等。示例结构参见 REST API 元数据文档{ request: { url: https://dummyjson.com/users, method: GET, headers: { user-agent: got (https://github.com/sindresorhus/got) }, params: {} }, response: { statusCode: 200, headers: { content-type: application/json; charsetutf-8 } } }访问技巧当访问含连字符的属性如user-agent时应使用方括号记法{{queries.restapi1.metadata.request.headers[user-agent]}}。服务端实现印证在查询执行完成后服务端会将查询状态中的响应元数据合并进结果对象的metadata字段并对restapi/grpcv2类型额外补充queryDefinition参见 server/src/modules/data-queries/util.service.ts同时 REST API 的set-cookie响应头仍会被回写给客户端供应用侧处理 Cookie同文件 util.service.ts 与 setCookiesBackToClient。升级后的自托管注意事项附对于自托管部署非 Cloud升级 3.0 后还需注意一项系统级变更详见 自托管升级指南ToolJet Database 成为核心依赖使用 ToolJet Database 需要部署并运行PostgREST服务器来查询 ToolJet Database需配置的环境变量参见 环境变量文档 中的 PostgREST 与 ToolJet Database 相关章节。Cloud 用户无需自行处理该部分自托管用户请在升级前完成 PostgREST 的部署与环境变量配置。结语升级检查清单速览检查项核心动作高风险信号动态输入限制全部改为静态组件引用components[变量]、字符串拼接组件名组件/查询命名升级前临时改名记录映射组件与查询同名且互相引用属性面板变量逻辑改用?? false检查存在性in/Object.keys/hasOwnProperty多页面组件命名跨页面唯一命名或改用查询参数多页同名组件 查询绑定旧 Kanban Board迁移到新版 Kanban 组件仍在使用旧看板组件本地数据源迁移为全局数据源查询报本地数据源不再支持工作区变量替换为工作区常量仍在引用 Workspace Variables响应头访问改用queries.name.metadata代码中出现responseHeaders按上表逐项审查、改造、回归测试即可确保应用在 ToolJet 3.0 自动升级后平稳运行。若在迁移过程中发现问题可通过官方 Slack 社区求助或提交 GitHub issue 反馈。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考