ToolJet 工作区变量Workspace Variables完整指南跨应用复用密钥的%%语法、类型与弃用说明【免费下载链接】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 仓库docs/versioned_docs/version-2.50.0-LTS/org-management/workspaces/workspace-variables.md编写并结合后端实体与查询解析源码进行佐证。ToolJet 工作区变量Workspace Variables是一种工作区级别的环境变量机制用于把 API Key、Token、密钥等敏感值集中管理并在同一工作区下的多个应用中复用。本文将从添加变量的完整操作步骤、Client / Server 两种变量类型、加密机制、%%专用引用语法到它在查询与全局数据源连接表单中的解析原理给出完整的实战说明同时明确其在当前版本2.50.0-LTS中的弃用状态与替代方案 Workspace Constants。:::caution 弃用警告 工作区变量当前已被标记为deprecated已弃用将在未来版本中移除。在当前版本中你仍然可以删除已存在的变量并继续在任意 ToolJet 应用中使用它们但创建和更新变量已不再受支持。官方建议改用 Workspace Constants工作区常量 作为替代方案。 :::一、什么是工作区变量工作区变量是带有某个值通常是 token、密钥、API Key 等的变量它可以在同一个工作区下的不同应用之间共享使用。与某个具体应用绑定的普通变量不同工作区变量从创建那一刻起就属于整个工作区任何具备相应权限的应用都能引用它。从数据模型上也可以印证这一点后端实体 org_envirnoment_variable.entity.ts 中工作区变量对应数据库表org_environment_variables其中包含variable_name变量名称value变量值variable_type变量类型枚举取值client或serverencrypted是否加密organization_id所属工作区组织ID通过ManyToOne关联到组织实体。也就是说变量归属维度是organization_id工作区/组织而非某个应用这正是它能够跨应用复用的底层原因。二、如何向工作区添加变量当工作区中存在一个需要被多个应用反复使用的API Key或某个固定值时工作区管理员或拥有相应权限的用户就可以添加一个环境变量。添加环境变量的操作步骤进入 ToolJet 仪表盘Dashboard点击导航栏上的下拉菜单展开Workspace选项选择Manage Environment Variables管理环境变量点击Add New Variable添加新变量按钮为变量设置Name名称、value值选择Type类型切换Encryption加密开关最后点击Add Variable添加变量按钮完成以上步骤后该变量即可被这个工作区内的任意应用使用。:::info 类型不可变变量类型Type一旦创建便无法更改。因此在创建前需要明确该变量是作为 Client 变量还是 Server 变量使用避免创建后发现类型不匹配而无法修改当前版本也不再支持更新操作。 :::变量类型说明类型可使用的场景限制与安全考虑Client客户端变量组件components、查询queries、全局数据源global datasources无额外限制Server服务端变量除RunJS和全局数据源连接表单之外的所有查询不能在组件中使用Server 变量为什么不能用于组件因为 Server 变量的解析仅发生在运行时runtime即请求在服务端执行查询的那一刻才会被替换成真实值。客户端组件在渲染阶段无法获取到这些值这种设计确保了服务端变量具有较高的安全性——敏感值不会下发到浏览器端。从源码上看服务端确实承担了变量的解析职责在>%%client.pi%%其中client是变量类型前缀pi是变量名称。为什么不能用{{ }}文档明确说明环境变量工作区变量不会在 js 代码{{ }}内部生效。两者是两套独立的解析通道混用会导致变量无法被正确解析。注意事项必须使用点号dot记法:::warning 服务端变量不支持方括号记法 服务端变量在服务端解析而服务端不支持方括号记法bracket notation。如果在服务端执行的查询中使用了方括号记法引用工作区变量该查询将会失败。请务必使用点号记法如%%client.pi%%在查询中解析工作区变量。 :::Client 变量使用示例在查询或组件属性中直接输入%%client.api_key%%该值会在客户端侧被解析替换可用于组件属性、查询参数以及全局数据源的连接配置中。Server 变量使用示例在服务端执行的查询如 REST API 查询的请求体、PostgreSQL / MySQL 等数据源查询语句中引用%%server.database_password%%该值会在查询执行时于服务端被替换不会暴露给浏览器端。全局数据源连接表单中使用 Server 变量自 ToolJet 版本2.10.0起Server 类型的工作区变量也可以在全局数据源global datasources的连接表单中使用。这意味着工作区级的数据库密码、Token 等凭据可以在全局数据源配置里直接引用无需在每个查询中重复硬编码敏感信息。四、底层解析原理源码佐证从服务端源码可以进一步印证上述行为在 contenteditable="false">【免费下载链接】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），仅供参考
