ToolJet 应用预览与分享部署完整指南：公开分享、自定义 URL 与 iframe 嵌入

导读

在 ToolJet 中构建完成内部工具或业务应用后，如何快速验证效果、并把应用分享给团队或外部用户，是落地使用的关键一步。本篇指南基于官方教程文档（sharing-and-deploying.md），结合 ToolJet 前端源码，完整讲解「预览当前版本」「发布后公开分享」「自定义分享 URL」「iframe 嵌入应用」四条核心路径，并深入剖析其底层实现——包括公开开关如何写入后端、slug 的命名校验规则、以及嵌入模式下基于 Personal Access Token（PAT）的会话建立流程。读完本文，你将能够熟练完成 ToolJet 应用的预览、公开分享与第三方页面嵌入。

预览（Preview）：在浏览器中即时检查当前版本

ToolJet 编辑器右上角提供 Preview 按钮。点击后，会在浏览器新标签页中打开当前正在编辑的版本的应用，方便你以接近生产环境的方式立即检查应用的实际效果，而不必先执行发布操作。

从源码实现看，预览链接由 RightTopHeaderButtons.jsx 中的 PreviewAndShareIcons 组件动态构造：

const previewQuery = queryString.stringify({
  version: selectedVersion?.display_name || selectedVersion?.displayName || selectedVersion?.name,
  ...(featureAccess?.multiEnvironment ? { env: selectedEnvironment?.name } : {}),
});
setAppPreviewLink(
  editingVersion
    ? `/applications/${slug || appId}/${currentPageHandle}${!isEmpty(previewQuery) ? `?${previewQuery}` : ''}`
    : ''
);

这段代码揭示了预览功能的两个关键细节：

• 预览 URL 会携带 version 查询参数，指向当前选中的版本名称；只有当实例启用了多环境（featureAccess.multiEnvironment）时，才会额外附加 env 参数以定位到当前环境。
• 预览链接只在存在「正在编辑的版本」时生成；如果处于已发布等状态，链接为空，预览入口不可用。

分享应用（Sharing an app）的前提：先发布版本

分享前有一个前置条件：必须先发布（release）一个版本。只有发布后的版本才允许被分享给他人。发布流程与版本管理相关，可在编辑器的版本管理器中完成，随后即可通过下方步骤生成对外可访问的链接。

第一步：打开 Share 对话框

点击编辑器右上角的 Share 按钮（带分享图标），即可打开分享对话框。

从源码看，该按钮由 ManageAppUsers 组件渲染（ManageAppUsers.jsx），点击后会先对已存在的 slug 做一次合法性校验，再弹出 Modal 对话框：

<Button
  data-cy="editor-app-share-button"
  variant="ghost"
  iconOnly
  onClick={() => {
    this.validateThePreExistingSlugs();
    this.setState({ showModal: true });
  }}
>
  <Share2 width="16" height="16" />
</Button>

第二步：打开「Make the application public」公开开关

在分享对话框中，将 Make the application public（使应用公开）开关切换为开启状态，应用即可被任何持有链接的人访问。

该开关的底层实现调用 appsService.setVisibility(appId, newState) 将应用可见性写入后端（ManageAppUsers.jsx）：

toggleAppVisibility = () => {
  const newState = !this.props.isPublic;
  ...
  appsService
    .setVisibility(this.state.appId, newState)
    .then(() => {
      if (newState) {
        toast('Application is now public.');
      } else {
        toast('Application visibility set to private');
      }
    })
    ...
};

开启后界面会提示 "Application is now public."，关闭则提示应用恢复为私有。isPublic 状态同时保存在应用级 store 中，供界面同步刷新。

注意（Git 分支锁定）：若工作区启用了 Git 多分支同步，且当前处于默认/master 分支，分享配置（公开开关与 slug 编辑）会被锁定——界面上开关呈禁用态，并提示 "Master branch is locked. Switch branch to make the application public."。需要切换到功能分支才能修改分享设置，改动合并回默认分支后全局生效（ManageAppUsers.jsx）。

第三步：定制分享 URL（slug）

开启公开后，可以为应用创建自定义 URL（即 slug）。分享链接的格式为：

{宿主地址}/applications/{slug 或 appId}

在分享对话框中，可以直接编辑 slug 文本框（最多 50 个字符），输入时组件会做防抖处理（500ms），并通过 appsService.setSlug(appId, value) 实时向后端提交校验与保存（ManageAppUsers.jsx）。

slug 的命名规则（来自前端通用校验函数 utils.js 的 validateName，应用于 slug 时禁用了特殊字符与空格）：

• 只允许小写字母、数字与连字符（-）（正则 ^[a-z0-9 -]+$）；
• 不允许包含空格（"Cannot contain spaces"）；
• 不允许包含特殊字符（"Special characters are not accepted."）；输入大写字母会提示 "Only lowercase letters are accepted."；
• 长度上限 50 个字符；
• 不能为空。

校验通过后，界面显示 "Slug accepted!"，并在输入框旁显示绿色对勾；如果与现有应用冲突或校验失败，则显示红色错误信息。保存成功后，编辑器地址栏也会同步更新（调用 replaceEditorURL）。

复制分享链接

定制好 slug 后，点击 URL 输入框右侧的 copy（复制）图标，即可将完整分享链接复制到剪贴板，随后通过邮件、IM 等渠道发给目标用户。源码中使用 react-copy-to-clipboard 的 CopyToClipboard 组件实现，复制成功会弹出 "Link copied to clipboard" 提示（ManageAppUsers.jsx）。

嵌入（Embed）应用：iframe 集成到第三方页面

除了直接分享链接，ToolJet 还支持将应用嵌入到自己的网站或系统中。分享对话框中提供了 Embedded app link（嵌入应用链接），它是一段可直接粘贴到 HTML 页面的 iframe 代码，由前端实时生成（ManageAppUsers.jsx）：

<iframe
  width="560"
  height="315"
  src="{宿主地址}/applications/{slug}"
  title="{白标应用名} app - {slug}"
  frameborder="0"
  allowfullscreen
></iframe>

将这段代码放入任意支持 iframe 的页面，即可把 ToolJet 应用内嵌展示。

嵌入链接的可见条件：只有应用处于公开状态、或实例开启了 ENABLE_PRIVATE_APP_EMBED（允许私有应用嵌入）配置时，嵌入链接区域才会显示（ManageAppUsers.jsx）。

私有应用嵌入的原理（源码级解析）

针对私有应用的嵌入场景，ToolJet 提供了一条基于 Personal Access Token（PAT） 的嵌入流程。入口组件 EmbedApp.jsx 的实现要点如下：

1. iframe 环境校验：组件会检查 window.self === window.top，若页面不是在 iframe 中打开，则提示 "This page must be embedded inside a parent application." 并中止；
2. 获取令牌：从 URL 查询参数 personal-access-token 中读取 PAT；
3. 建立会话：调用 ${config.apiUrl}/ext/users/session 接口，携带 appId 与 accessToken 换取签名 PAT（signed PAT）；
   • 若返回 401/403，表示令牌过期或无效，会向父页面发送 TJ_EMBED_APP_LOGOUT 消息，方便宿主应用感知并处理登录态；
4. 会话保持：签名 PAT 缓存在内存变量与 window.name 中（同一标签页内导航可跨页面保持），随后重定向到 applications/{appSlug} 正常渲染应用。

小结与最佳实践

回顾 ToolJet 应用的预览与分享全流程：

环节	操作	关键点
预览	点击编辑器右上角 Preview	新标签页打开当前版本，URL 带 version/env 参数
发布	先在版本管理器发布一个版本	分享的前置条件
公开	Share 对话框开启 Make the application public	写入 isPublic 状态，Git 多分支下默认分支被锁定
定制 URL	编辑 slug	小写字母、数字、连字符，≤50 字符，无空格无特殊字符
复制链接	点击 copy 图标	链接格式为 {host}/applications/{slug}
嵌入	复制 Embedded app link	使用 iframe；私有应用需 PAT + ENABLE_PRIVATE_APP_EMBED

实践建议：

• 分享前务必先发布目标版本，确保外部用户看到的是你期望的稳定版本；
• slug 是分享链接的可读标识，建议使用简短、语义化的小写连字符命名（如 customer-onboarding），并利用实时校验反馈确保其合法可用；
• 若要在自己的门户中嵌入应用，优先使用公开分享；涉及敏感数据时，评估私有嵌入方案，并妥善管理 PAT 的签发与过期；
• 多分支 Git 工作流下，分享配置的修改请切到功能分支进行，合并后即全局生效。

通过以上步骤，你可以在 ToolJet 中完成从「本地预览」到「对外发布分享」再到「站点内嵌」的完整应用交付链路。