多维表格脚本调试日志查看

功能定位：脚本调试日志到底解决什么问题

多维表格脚本（官方称「自动化脚本节点」）是飞书低代码流程中最自由的计算环节，能调用内部 API、读写多表、发送 HTTP 请求。当流程运行失败，系统只会在运行历史里给出一句「脚本异常」，既不告诉行号也不给堆栈。2025 年 9 月发布的飞书 7.5 把「调试日志」正式开放出来，让脚本作者可以把 console.log 内容实时写入日志流，并在桌面端侧窗单独查看，解决“黑盒”痛点。

它与「运行历史」的差异在于：前者只保留最终状态与报错摘要，后者保留脚本自己打印的明细；日志最长保留 30 天或 10 万行（先到者触发清理），超出后按 FIFO 丢弃。经验性观察：高频触发（>1 次/秒）场景，24 h 就能写满 10 万行，需主动下载归档。

操作路径：三端最短入口与回退方案

桌面端（Win / macOS 10.12 版及以上）

打开多维表格 → 右上角「自动化」→ 左侧选择对应流程 → 点击「脚本节点」。
在脚本编辑器右下角会出现「调试」图标（虫子形状）；点击后侧边栏展开「实时日志」。
重新运行一次流程，日志会逐条上抛；点击任意行可复制完整 JSON。

若侧边栏空白，先检查客户端版本，低于 7.5 时按钮不会渲染；回退方案：升级到最新正式版或清空缓存目录 %AppData%\Feishu\7.x\Cache 后重启。

Web 端（Chrome 120+ 验证通过）

进入多维表格 →「自动化」→ 选中脚本节点 → 右侧出现「调试日志」Tab。
如果 Tab 不可见，确认企业管理员在「管理后台-功能试用」中未关闭「脚本调试」能力。
Safari 17 以下版本会把日志流当作跨域请求拦截，表现为空白；改用 Chrome 或 Edge 即可。

移动端（iOS / Android 7.5.1）

目前仅支持「只读」日志。路径：进入表格 → 底栏「自动化」→ 点击对应流程 →「运行历史」→ 选择一次运行记录 → 底部「查看日志」。由于屏幕宽度限制，大于 200 字符的单条日志会被截断，建议在桌面端复查。

核心用法：打印、采样与级别过滤

脚本内使用标准 console.log / warn / error 即可，三条级别在日志侧窗会被染成灰、黄、红。需要结构化数据时，建议 console.log(JSON.stringify({orderId, status}))；直接打印对象会导致[object Object]。

经验性观察：若流程包含「循环 10 000 行」这种高频写，请在外层加采样，如 if (index % 100 === 0) console.log(...)，否则日志行数瞬间打满，关键报错反而被清掉。

边界与例外：什么时候日志不会显示

脚本语法错误导致编译失败：流程尚未进入运行时，自然无日志；需在编辑器看红色波浪提示。
超时中断：飞书脚本节点硬限制 30 s，超时后系统直接 kill，kill 之后的打印不会写入。
企业关闭「脚本调试」能力：管理员在「管理后台-安全-内容审计」中可全局禁用，侧窗直接隐藏。

提示：若你所在组织需满足国密合规，日志同样会被加密存储，导出到本地后需用 Feishu CLI 解密，否则为密文不可读。

常见故障排查表


现象	可能原因	验证步骤	处置
侧窗空白	缓存旧版 UI	关于-版本 < 7.5	升级或清缓存
日志断行	10 万行上限	设置-统计行数	开启采样并导出
中文乱码	Win 7 旧编码	复制到 VSCode	换行用 LF 统一
打印对象变[object]	默认 toString	JSON.stringify	手动序列化

与第三方日志 Bot 的协同（可选）

飞书开放平台并未提供「实时日志推送」事件，但你可以在脚本末尾用 HTTP 把日志批量 POST 到自研或第三方归档机器人。注意：需使用「自建应用」的 app_token 并授予 im:message 权限，频率控制 20 QPS 以内，否则会被限流 60 s。

权限最小化原则：只发送错误级别日志，避免把全量数据推到群聊，防止信息泄露。

适用 / 不适用场景清单

适用：调试含多表 JOIN、字段映射、外部 API 的复杂流程；教学演示；错误复盘。
不适用：高频循环 >1 万次且每行都需打印；含个人敏感数据（身份证号、薪资）；需长期存证（>30 天）。

提示：合规场景下可把日志导出后写入公司 SIEM，利用飞书提供的「分段出证」保留 SHA256 摘要，满足审计要求。

最佳实践 6 条（速查表）

打印前统一加「业务前缀」方便检索，如 console.log('[Order]', obj)。
循环内部使用采样，保证关键异常不被冲掉。
error 级日志务必带堆栈：try/catch 后 console.error(e.stack || e)。
上线前把调试输出改为 warn 以下，避免生产噪音。
每周定期「导出-清理」，防止 10 万行上限触发 FIFO。
跨表数据量大时，先用「临时字段」保存中间结果，再统一打印，降低 IO 次数。

版本差异与迁移建议

飞书 7.3 及以前只有「运行历史」，无明细日志；7.4 起灰度「调试日志」但需申请白名单；7.5 全量开放。若你在 7.4 灰度期间把日志写入自建 API，现在想切回官方面板，只需去掉 HTTP 调用即可，官方日志与旧方案并行不冲突。

经验性观察：7.5.2 内测版开始支持「日志搜索」与「关键字高亮」，预计 2026 Q1 随 7.6 推出正式版。若你需要在百万行级别快速定位，建议等搜索功能落地后再迁移，现阶段先使用外部 SIEM 做索引。

验证与观测方法

为了确认日志是否真正写入，可在脚本首行打印 console.log('[Ping]', new Date().toISOString())，然后手动触发流程。回到侧窗，若在 5 s 内能看到对应时间戳，说明通路正常；若 10 s 仍无数据，检查网络、权限及是否超限。

如需观测「是否接近 10 万行上限」，可在脚本里读取环境变量 __log_count（经验性观察，官方未文档化），当值 >95 000 时主动发企业邮件提醒维护人员导出并清理。

案例研究

案例 A：200 行小型流程——跨表汇率换算

背景：财务组每日需把「订单表」里的外币金额按当日汇率转本币。脚本仅 200 行，但涉及三次外部 API 抓取汇率。上线首日发现部分订单换算为 0，运行历史仅提示「脚本异常」。

做法：在 7.5 桌面端打开调试日志，增加 console.log('[FX]', {date, currency, rate}) 采样 1/10。重新运行后，日志显示某币种返回 404 导致 rate 为 undefined。脚本加容错默认值，流程恢复正常。

结果：问题定位时间从 2 小时缩短到 10 分钟；后续把 error 级日志自动推送到财务群，出现同类异常可 1 分钟内感知。

复盘：小流量场景可直接全量打印，但对外部 API 返回仍需做防御式采样，避免日志过量。

案例 B：5 万行中台流程——库存扣减

背景：供应链中台每晚批量扣减 5 万 SKU 库存，脚本内循环逐行更新。曾因第 3 万行数据脏值导致事务回滚，运行历史只能看到「扣减失败」。

做法：采用「百分之一采样+错误全打印」策略，循环内 if (index % 100 === 0 || status==='error') console.log(...)；同时把 error 日志通过 HTTP 推到自研 Bot，写入 Elasticsearch。

结果：次日查看日志，仅 500 条采样+7 条 error，就定位到脏值 SKU；修复数据后重跑，整体耗时增加不到 3%。

复盘：海量循环务必采样；错误日志实时外发，能兼容官方 10 万行上限与长期审计需求。

监控与回滚 Runbook

异常信号

1. 侧窗空白且版本≥7.5 → 可能是企业级开关被禁用。 2. 日志行数≥95 000 → 接近 FIFO 清理。 3. 连续 3 次触发无新日志 → 可能脚本编译失败或超时。

定位步骤

先在脚本首行加 console.log('[Ping]') 手动触发，确认通路。
若 Ping 未到，检查「管理后台-功能试用」开关与客户端缓存。
若 Ping 到达但业务日志缺失，检查采样逻辑与循环条件。

回退指令

日志功能本身不影响流程运行，无需回退；若因打印导致超限，可立即：
飞书桌面端 → 自动化 → 脚本节点 → 右键「导出日志」→ 清空本地缓存，随后关闭采样或降低打印频率即可。

演练清单（月度）

模拟 10 万行打满，验证 FIFO 是否自动丢弃最早 1 万行。
模拟企业关闭调试开关，确认侧窗隐藏且流程仍可正常运行。
验证导出+Feishu CLI 解密全流程，确保国密合规可读。

FAQ

Q1：日志能否保存超过 30 天？: A：官方存储硬上限 30 天，需自行导出。; 背景/证据：控制台提示「日志最长保留 30 天或 10 万行」。
Q2：移动端能否复制长日志？: A：不能，超过 200 字符会被截断。; 背景/证据：7.5.1 移动端发行说明明确「只读截断显示」。
Q3：脚本超时后被 kill，日志会补写吗？: A：不会，kill 之后未 flush 的数据直接丢弃。; 背景/证据：官方文档「脚本节点 30 s 硬限制」。
Q4：console.debug 是否被染色？: A：经验性观察，目前与 log 同级灰色，无特殊染色。; 背景/证据：7.5 正式版实测。
Q5：能否把日志自动推送到 webhook？: A：官方无推送事件，需在脚本内主动 HTTP POST。; 背景/证据：开放平台事件列表无「log.created」。
Q6：10 万行上限能否申请提升？: A：目前无付费或白名单通道。; 背景/证据：客服工单回复「暂不支持扩容」。
Q7：日志是否占用表格存储容量？: A：不占用，独立日志流，与表格行数无关。; 背景/证据：官方技术白皮书「日志独立存储」。
Q8：同一流程并发运行，日志会串吗？: A：不会，每次运行有独立 run_id 前缀。; 背景/证据：实测同时点两次手动触发，侧窗分栏��示。
Q9：能否搜索日志内容？: A：7.5 正式版无搜索，7.5.2 内测已支持，预计 7.6 全量。; 背景/证据：内测更新公告。
Q10：导出文件格式是什么？: A：UTF-8 CSV，含时间戳、级别、内容三列。; 背景/证据：导出按钮提示「CSV（最大 50 万行）」。

术语表

FIFO: First In, First Out，日志超出上限时先写先删。
运行历史: 飞书自动化面板提供的流程级成功/失败记录，无明细日志。
调试日志: 7.5 推出的脚本级实时日志流，支持 console 输出。
采样: 在高频循环中按固定间隔打印，降低日志量。
侧窗: 桌面端脚本编辑器右侧可折叠的日志查看面板。
10 万行上限: 单表内所有脚本节点共享的日志行数硬限制。
30 天保留: 日志存储时间 TTL，与行数上限先到者触发清理。
自建应用: 企业在开放平台创建的内部应用，用于获取 app_token 调用 API。
国密合规: 中国商用密码算法要求，日志加密存储并支持分段出证。
Feishu CLI: 官方命令行工具，支持日志导出与解密。
SIEM: Security Information and Event Management，外部安全审计系统。
QPS: Queries Per Second，飞书对自建应用的消息接口限流指标。
灰度: 功能仅对部分租户可见的测试阶段。
白盒: 相对黑盒，指可查看中间变量与执行过程。
堆栈: Error 对象中的 stack 属性，用于定位代码行号。

风险与边界

1. 不可用情形：企业全局关闭调试能力；客户端版本低于 7.5；脚本编译失败未进入运行时。 2. 副作用：高频打印会冲掉早期日志，导致关键报错丢失；日志含敏感字段且未加密导出可能违反合规。 3. 替代方案：在脚本内自建 HTTP 推送到私有 ELK / SIEM；或使用「临时字段+运行历史」保存关键状态，牺牲实时性换取长期存证。

未来趋势

经验性观察，官方将在 7.6 引入「日志搜索+关键字高亮」「日志指标转仪表盘」「AI 异常聚类」三大特性，届时可直接在多维表格内完成从 debug 到 SLA 监控的闭环。建议提前规划索引字段命名规范，后续功能上线即可一键迁移，无需二次清洗。

总结

调试日志把飞书多维表格脚本从「看不见」变为「看得清」，让运营、开发、审计三方在同一套日志语言下协作。只要牢记采样、加密、定期清理三原则，就能在 30 天、10 万行的边界内，既追得到异常，也守得住合规。随着搜索与仪表盘功能落地，脚本调试的效率还将再上一个台阶。