企业官网建设流程全解析

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 日之前完成，否则应用可能中断甚至崩溃。 :::

在动手改造前，建议先完成以下准备工作（自托管场景同样适用，参见同仓库的 自托管升级指南）：

1. 数据库备份：对业务数据库做完整备份；
2. 应用清单审查：逐项核对本文列出的破坏性变更与已弃用功能；
3. 测试环境先行：先在测试环境完成升级演练，再处理生产应用。

动态输入限制（Dynamic Input Restrictions）

3.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 Logic）

3.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）而非直接引用组件；
• 记录所有组件名变更；
• 测试受影响页面及其相互交互。

当前限制与细节

当同名组件出现在多个页面并与查询关联时，该查询只在组件最初被关联的那个页面上正常工作。

典型场景：

1. page1和page2中各有一个名为textinput1的组件；
2. 在page1创建了一条关联textinput1的查询；
3. 该查询仅在page1上正常工作；
4. 切换到page2时，即使那里存在同名组件，查询也不会按预期工作。

:::tip 构建多页面应用时，建议在所有页面中使用唯一的组件名称，以避免查询绑定出现潜在问题。 :::

后续规划：官方将在后续版本中增加"跨页面强制组件名称唯一"的功能。在此之前，建议通过团队命名规范（如按页面前缀命名组件：page1_textinput1）提前规避。

已弃用功能的移除（Removal of Deprecated Features）

旧版 Kanban Board 组件

旧版已弃用的Kanban Board组件将彻底停止工作。升级后若未处理，使用该组件的应用将直接崩溃。

必需操作

1. 立即识别应用中所有旧版Kanban Board组件；
2. 使用新版Kanban组件创建新的看板；
3. 将数据与配置迁移到新组件；
4. 移除所有旧版 Kanban Board 组件；
5. 更新所有连接到旧看板的查询或工作流；
6. 全面测试，确保原有功能完整保留。

:::caution 11 月 11 日之后，包含旧版 Kanban Board 组件的应用将崩溃且无法使用。 :::

本地数据源（Local Data Sources）

自 ToolJet 3.0.0 起，本地数据源（Local Data Sources）已被完全停用（更早版本中已弃用，3.0 彻底移除支持）。

升级前操作

• 识别应用中所有的本地数据源；
• 将其迁移为全局工作区数据源（global workspace data sources）；
• 更新所有使用这些数据源的查询与组件；
• 迁移后测试所有受影响的组件与查询。

升级后补救

如果升级前未完成迁移，查询将显示"本地数据源不再受支持"的错误提示。具体补救步骤（参见 本地数据源迁移指南）：

1. 定位报错查询：进入应用 → 展开查询管理器（Query Manager）→ 找到显示本地数据源错误的查询（该查询只会显示错误信息，其余内容被隐藏）；
2. 创建新数据源：进入Data Sources区域，创建同类型的新数据源（例如原 PostgreSQL 本地数据源 → 新建 PostgreSQL 数据源），填写正确配置并保存；
3. 重新连接查询：回到应用，打开报错查询，在Source字段的下拉框中选择新建的同类型数据源，查询即恢复连接；
4. 测试查询：逐个运行更新后的查询，确认一切符合预期。

工作区变量（Workspace Variables）

升级前操作

• 识别所有使用工作区变量的场景；
• 将其替换为工作区常量（Workspace Constants）；
• 更新所有使用这些变量的组件与查询；
• 为新常量配置合适的基于角色的访问权限；
• 迁移后测试所有受影响功能。

为什么迁移到工作区常量：工作区常量仅在服务端解析，客户端无法接触，安全性更高；同时可按角色为用户分配对工作区常量的创建、更新、删除权限。这一点在源码中也有印证——服务端数据源工具服务在解析数据源选项时专门处理workspace_constant字段并写入凭据服务（参见 server/src/modules/data-sources/util.service.ts），且禁止在默认（master）分支上直接添加工作区常量（同文件 util.service.ts），加密字段中的常量必须走 PR 工作流。

完整的迁移路径参见 工作区变量迁移指南：

1. 按照 创建工作区常量 的步骤，为每个变量值创建对应的常量；
2. 将应用/数据源中的工作区变量替换为对应的常量；
3. 全部迁移并充分测试后，到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; charset=utf-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 的部署与环境变量配置。

结语：升级检查清单速览

按上表逐项审查、改造、回归测试，即可确保应用在 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