ToolJet Debugger 调试器完整指南捕获查询错误、组件属性校验与日志排查【免费下载链接】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 应用编辑器左侧栏中的 Debugger调试器面板讲解它如何捕获并展示数据查询运行错误、组件属性校验错误与事件执行错误以及固定Pin面板、日志分级与逐条展开排查等核心用法并结合前端源码深入剖析日志的产生、分类与展示机制。Debugger 是 ToolJet 应用编辑器内置的运行时错误捕获与排查工具。当你在画布上运行数据库查询如 PostgreSQL、MySQL 查询因数据库不可用而失败、REST API 调用如因 URL 错误而失败或触发组件事件链时Debugger 都会捕获这些错误并在左侧栏面板中集中展示。本文将以 version-3.0.0-LTS 教程文档 为骨架结合前端源码frontend/src/AppBuilder/LeftSidebar/Debugger/及frontend/src/AppBuilder/_stores/slices/下的状态切片带你掌握 Debugger 的完整用法与底层实现原理。Debugger 是什么左侧栏的运行时错误捕获面板Debugger 面板位于应用编辑器的左侧栏left-sidebar。按照教程文档的定义它专门捕获查询query运行过程中发生的错误典型场景包括数据库查询失败例如数据库不可用unavailability of a database、连接被拒绝、SQL 语法错误REST API 查询失败例如 URL 填写错误、接口返回 4xx/5xx、网络超时其他查询类型如 ToolJet Database、GraphQL、SMTP 等运行时报错。错误产生后Debugger 不仅显示错误消息还会展示与该错误相关的数据例如请求对象、响应对象、替换后的变量等帮助你定位根因。从源码看Debugger 面板的入口组件位于 Debugger.jsx它在左侧栏中被注册为debugger菜单项见 LeftSidebar.jsxcase debugger: return Debugger onClose{() toggleLeftSidebar(false)} darkMode{darkMode} /;日志的产生谁在向 Debugger 写入数据所有日志都经由 Zustand 状态切片debuggerSlice统一管理其初始状态包含三个字段见 debuggerSlice.jsconst initialState { logs: [], // 日志列表 unreadErrorCount: 0, // 未读错误计数驱动左侧栏角标 pinned: false, // 是否固定面板 };写入日志的入口主要有两个log(log)将单条日志插入到列表头部unshift若logLevel error则未读错误计数加一logMultiple(logs)批量写入多条日志例如一次组件校验产生多条错误避免多次触发 Zustand 的set()。日志会自动携带当前页面 IDlog.page get().getCurrentPageId(canvas)这样在多页面应用中Debugger 可以按页面过滤日志——Debugger.jsx中正是用logs.filter((log) log.page currentPageId)只展示当前页面的日志而 All logs 标签页则展示全部。查询执行路径的日志查询运行的核心逻辑位于 queryPanelSlice.js成功、失败、跳过三种情况都会写日志成功logLevel: successisQuerySuccessLog: true消息Query executed successfully见 queryPanelSlice.js失败logLevel: error消息为错误描述REST API 失败时还会附上substitutedVariables替换后的变量、request请求对象、response响应对象见 queryPanelSlice.js跳过logLevel: info消息Query skipped: ...例如查询被禁用或条件不满足见 queryPanelSlice.js。事件执行路径的日志组件事件如按钮的onClick、查询的onDataQueryFailure执行出错时由eventsSlice.logError()统一写入日志见 eventsSlice.js。它会构造一个高度结构化的标题例如[Page 首页] [Component Button1] [Event onClick] [Action run-query]以及对应的事件来源分类errorTargetEvent Errors with page、Component Event、Event Errors with query等。这正是 Debugger 每条日志中错误目标errorTarget与带高亮第二词的标题的由来——渲染组件 Logs.jsx 中的HighlightSecondWord会把[Action run-query]这类片段中的动作名加粗显示。另外log-info/log/log-error三类动作会在 Debugger 中产生Custom Log自定义日志常用于在事件处理中主动输出调试信息见 eventsSlice.js。组件属性校验路径的日志Debugger 的另一重要职责是组件属性Property校验。在debuggerSlice中validateComponents()/validateComponent()会依据组件元数据componentTypeDefinitionMap中的 validation 定义对组件的 properties、styles、general、generalStyles 逐项校验任何非法值都会产生一条type: component、logLevel: error、errorTarget: Component Property的日志见 debuggerSlice.jsvalidateProperty()则在单属性变更时实时校验校验失败会自动回退到默认值并记录日志日志的error对象里同时包含resolvedProperty开发者写入的原始值与effectiveProperty实际生效的默认值便于对比排查见 debuggerSlice.js。例如在表格列上绑定了非法的数据类型、给数字属性填了字符串Debugger 都会提示Invalid property detected: ...见 Logs.jsx。查看与交互日志条目、展开详情、复制与定位Debugger 面板头部SidebarDebuggerHeader.jsx提供两个标签页切换All logs展示全部日志含成功、信息、错误Errors仅展示logLevel error的错误日志过滤逻辑见 Debugger.jsx。头部右侧还有两个操作按钮清空日志垃圾桶图标触发clear同时重置未读计数与关闭面板x图标。逐条展开错误详情每条日志默认折叠显示一行摘要标题 错误消息 相对时间。点击日志条目可展开此时会以JSON 树视图JSONTreeViewer呈现error对象中的完整结构——例如 REST API 查询失败时的request/response/substitutedVariables组件校验失败时的resolvedProperty/effectiveProperty见 Logs.jsx。展开后的 JSON 树支持两个动作callbackActions见 Logs.jsxCopy value把某个节点值序列化后复制到剪贴板提示Value copied to clipboardSelect Widget当错误与某个组件相关时一键在画布上选中该组件通过componentId在组件映射中查找便于直接跳转修复。时间戳使用moment(...).fromNow()展示为 3 minutes ago 这类相对时间。未读角标左侧栏的 Debugger 图标Bug 图标上会显示unreadErrorCount角标每产生一条 error 级日志计数加一点击打开 Debugger 时调用resetUnreadErrorCount()清零见 LeftSidebar.jsx。固定PinDebugger保持面板常开默认情况下Debugger 面板与左侧栏其他面板一样点击其他区域或再次点击图标时会自动收起。如果你希望调试过程中面板始终可见可以使用固定功能打开 Debugger 面板点击面板右上角的Pin图钉图标固定后面板将保持打开状态直到你再次点击 Pin 取消固定。固定状态由debuggerSlice中的pinned字段管理setPinned(status)见 debuggerSlice.js。在 LeftSidebar.jsx 中可以看到它的实际作用——当面板处于固定状态时再次点击侧边栏图标不会关闭面板const handleSelectedSidebarItem (item) { if (item debugger) resetUnreadErrorCount(); setSelectedSidebarItem(item); localStorage.setItem(selectedSidebarItem, item); if (item selectedSidebarItem !pinned) { return toggleLeftSidebar(false); // 仅未固定时才关闭 } if (!isSidebarOpen) toggleLeftSidebar(true); };实践建议用 Debugger 排查典型问题结合文档描述与源码行为以下三类问题最适合用 Debugger 定位查询失败类运行查询后切换到 Debugger在 Errors 标签页查看[Query xxx]日志展开后检查 REST API 的请求/响应对象与替换后的变量确认 URL、请求头、环境变量是否生效组件属性类绑定错误数据类型的属性后Debugger 会显示Invalid property detected可借助 Select Widget 一键选中出问题的组件或对照resolvedProperty与effectiveProperty判断是否被回退为默认值事件链路类组件事件执行失败时按[Page] [Component] [Event] [Action]的结构化标题快速定位是哪一步动作失败例如查询成功事件回调中引用了不存在的组件。使用小贴士调试期间将面板 Pin 住避免频繁开关用 All logs 观察成功与失败的完整执行序列用 Errors 聚焦错误确认问题后点击垃圾桶图标清空日志保持面板干净。扩展阅读Debugger 教程原文左侧栏面板总览Debugger 渲染实现Debugger.jsx、SidebarDebugger.jsx、Logs.jsx日志状态管理debuggerSlice.js、queryPanelSlice.js、eventsSlice.js【免费下载链接】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），仅供参考 ToolJet Debugger 调试器完整指南：捕获查询错误、组件属性校验与日志排查
ToolJet Debugger 调试器完整指南捕获查询错误、组件属性校验与日志排查【免费下载链接】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 应用编辑器左侧栏中的 Debugger调试器面板讲解它如何捕获并展示数据查询运行错误、组件属性校验错误与事件执行错误以及固定Pin面板、日志分级与逐条展开排查等核心用法并结合前端源码深入剖析日志的产生、分类与展示机制。Debugger 是 ToolJet 应用编辑器内置的运行时错误捕获与排查工具。当你在画布上运行数据库查询如 PostgreSQL、MySQL 查询因数据库不可用而失败、REST API 调用如因 URL 错误而失败或触发组件事件链时Debugger 都会捕获这些错误并在左侧栏面板中集中展示。本文将以 version-3.0.0-LTS 教程文档 为骨架结合前端源码frontend/src/AppBuilder/LeftSidebar/Debugger/及frontend/src/AppBuilder/_stores/slices/下的状态切片带你掌握 Debugger 的完整用法与底层实现原理。Debugger 是什么左侧栏的运行时错误捕获面板Debugger 面板位于应用编辑器的左侧栏left-sidebar。按照教程文档的定义它专门捕获查询query运行过程中发生的错误典型场景包括数据库查询失败例如数据库不可用unavailability of a database、连接被拒绝、SQL 语法错误REST API 查询失败例如 URL 填写错误、接口返回 4xx/5xx、网络超时其他查询类型如 ToolJet Database、GraphQL、SMTP 等运行时报错。错误产生后Debugger 不仅显示错误消息还会展示与该错误相关的数据例如请求对象、响应对象、替换后的变量等帮助你定位根因。从源码看Debugger 面板的入口组件位于 Debugger.jsx它在左侧栏中被注册为debugger菜单项见 LeftSidebar.jsxcase debugger: return Debugger onClose{() toggleLeftSidebar(false)} darkMode{darkMode} /;日志的产生谁在向 Debugger 写入数据所有日志都经由 Zustand 状态切片debuggerSlice统一管理其初始状态包含三个字段见 debuggerSlice.jsconst initialState { logs: [], // 日志列表 unreadErrorCount: 0, // 未读错误计数驱动左侧栏角标 pinned: false, // 是否固定面板 };写入日志的入口主要有两个log(log)将单条日志插入到列表头部unshift若logLevel error则未读错误计数加一logMultiple(logs)批量写入多条日志例如一次组件校验产生多条错误避免多次触发 Zustand 的set()。日志会自动携带当前页面 IDlog.page get().getCurrentPageId(canvas)这样在多页面应用中Debugger 可以按页面过滤日志——Debugger.jsx中正是用logs.filter((log) log.page currentPageId)只展示当前页面的日志而 All logs 标签页则展示全部。查询执行路径的日志查询运行的核心逻辑位于 queryPanelSlice.js成功、失败、跳过三种情况都会写日志成功logLevel: successisQuerySuccessLog: true消息Query executed successfully见 queryPanelSlice.js失败logLevel: error消息为错误描述REST API 失败时还会附上substitutedVariables替换后的变量、request请求对象、response响应对象见 queryPanelSlice.js跳过logLevel: info消息Query skipped: ...例如查询被禁用或条件不满足见 queryPanelSlice.js。事件执行路径的日志组件事件如按钮的onClick、查询的onDataQueryFailure执行出错时由eventsSlice.logError()统一写入日志见 eventsSlice.js。它会构造一个高度结构化的标题例如[Page 首页] [Component Button1] [Event onClick] [Action run-query]以及对应的事件来源分类errorTargetEvent Errors with page、Component Event、Event Errors with query等。这正是 Debugger 每条日志中错误目标errorTarget与带高亮第二词的标题的由来——渲染组件 Logs.jsx 中的HighlightSecondWord会把[Action run-query]这类片段中的动作名加粗显示。另外log-info/log/log-error三类动作会在 Debugger 中产生Custom Log自定义日志常用于在事件处理中主动输出调试信息见 eventsSlice.js。组件属性校验路径的日志Debugger 的另一重要职责是组件属性Property校验。在debuggerSlice中validateComponents()/validateComponent()会依据组件元数据componentTypeDefinitionMap中的 validation 定义对组件的 properties、styles、general、generalStyles 逐项校验任何非法值都会产生一条type: component、logLevel: error、errorTarget: Component Property的日志见 debuggerSlice.jsvalidateProperty()则在单属性变更时实时校验校验失败会自动回退到默认值并记录日志日志的error对象里同时包含resolvedProperty开发者写入的原始值与effectiveProperty实际生效的默认值便于对比排查见 debuggerSlice.js。例如在表格列上绑定了非法的数据类型、给数字属性填了字符串Debugger 都会提示Invalid property detected: ...见 Logs.jsx。查看与交互日志条目、展开详情、复制与定位Debugger 面板头部SidebarDebuggerHeader.jsx提供两个标签页切换All logs展示全部日志含成功、信息、错误Errors仅展示logLevel error的错误日志过滤逻辑见 Debugger.jsx。头部右侧还有两个操作按钮清空日志垃圾桶图标触发clear同时重置未读计数与关闭面板x图标。逐条展开错误详情每条日志默认折叠显示一行摘要标题 错误消息 相对时间。点击日志条目可展开此时会以JSON 树视图JSONTreeViewer呈现error对象中的完整结构——例如 REST API 查询失败时的request/response/substitutedVariables组件校验失败时的resolvedProperty/effectiveProperty见 Logs.jsx。展开后的 JSON 树支持两个动作callbackActions见 Logs.jsxCopy value把某个节点值序列化后复制到剪贴板提示Value copied to clipboardSelect Widget当错误与某个组件相关时一键在画布上选中该组件通过componentId在组件映射中查找便于直接跳转修复。时间戳使用moment(...).fromNow()展示为 3 minutes ago 这类相对时间。未读角标左侧栏的 Debugger 图标Bug 图标上会显示unreadErrorCount角标每产生一条 error 级日志计数加一点击打开 Debugger 时调用resetUnreadErrorCount()清零见 LeftSidebar.jsx。固定PinDebugger保持面板常开默认情况下Debugger 面板与左侧栏其他面板一样点击其他区域或再次点击图标时会自动收起。如果你希望调试过程中面板始终可见可以使用固定功能打开 Debugger 面板点击面板右上角的Pin图钉图标固定后面板将保持打开状态直到你再次点击 Pin 取消固定。固定状态由debuggerSlice中的pinned字段管理setPinned(status)见 debuggerSlice.js。在 LeftSidebar.jsx 中可以看到它的实际作用——当面板处于固定状态时再次点击侧边栏图标不会关闭面板const handleSelectedSidebarItem (item) { if (item debugger) resetUnreadErrorCount(); setSelectedSidebarItem(item); localStorage.setItem(selectedSidebarItem, item); if (item selectedSidebarItem !pinned) { return toggleLeftSidebar(false); // 仅未固定时才关闭 } if (!isSidebarOpen) toggleLeftSidebar(true); };实践建议用 Debugger 排查典型问题结合文档描述与源码行为以下三类问题最适合用 Debugger 定位查询失败类运行查询后切换到 Debugger在 Errors 标签页查看[Query xxx]日志展开后检查 REST API 的请求/响应对象与替换后的变量确认 URL、请求头、环境变量是否生效组件属性类绑定错误数据类型的属性后Debugger 会显示Invalid property detected可借助 Select Widget 一键选中出问题的组件或对照resolvedProperty与effectiveProperty判断是否被回退为默认值事件链路类组件事件执行失败时按[Page] [Component] [Event] [Action]的结构化标题快速定位是哪一步动作失败例如查询成功事件回调中引用了不存在的组件。使用小贴士调试期间将面板 Pin 住避免频繁开关用 All logs 观察成功与失败的完整执行序列用 Errors 聚焦错误确认问题后点击垃圾桶图标清空日志保持面板干净。扩展阅读Debugger 教程原文左侧栏面板总览Debugger 渲染实现Debugger.jsx、SidebarDebugger.jsx、Logs.jsx日志状态管理debuggerSlice.js、queryPanelSlice.js、eventsSlice.js【免费下载链接】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），仅供参考