用 Base44 后端函数日志与工作流运行历史排查生产问题时…

在 Base44 应用中排查函数报错、定时任务或自动化失败等生产问题时，用日志与工作流运行历史定位根因。

适用场景

解决思路

1. 先验证认证：运行 `npx base44 whoami`；若未认证或 token 过期，让用户运行 `npx base44 login`。
2. 解析应用上下文：在已关联的本地项目中运行 `cat base44/.app.jsonc`，或显式指定 `npx base44 logs --app-id app_123`。
3. 使用可用命令：`base44 logs` 获取该应用的函数日志；`base44 workflows runs` 按最新在前列出工作流运行（失败的运行会带上失败的任务和底层错误）；`base44 workflows list` 列出该应用的工作流及其状态与运行摘要。
4. 理解日志不是写后即读：单次抓取没命中并不能证明什么，`base44 logs` 读取的索引落后于调用，刚触发函数后得到空结果是预期现象而非问题证据。
5. 实时调试用 `--follow`：在支持实时流的地方，日志行会在 1 秒内送达；不支持时 CLI 会提示并改为轮询（`Warning: Realtime logs are not available for this app — falling back to polling (lines may lag ~20-30s).`）。无论哪种情况 `--follow` 都是正确工具，无需自己选择。
6. 一次性抓取会滞后约 20-30 秒，这是摄取时间，不是过滤问题。
7. 输出为空时，要改变的变量是时间，绝不是标志位：等待并重跑同一条命令；扩大 `--limit`、去掉 `--level`、切换 `--order` 对尚未被摄取的行毫无作用，反复换标志正是 agent 把自己带向错误诊断的方式。
8. 能触发失败或失败正在发生时，先运行 `npx base44 logs --follow` 或 `npx base44 logs --follow --function <function_name>`，然后调用函数并读取到达的日志。
9. 不要按定时器做判断：打开流、触发函数、一直读到看见日志行，不要读固定时间窗口后打印并断定“坏了”；流安静是因为还没有任何调用。
10. 投递是按调用而非按行的：长时间运行的函数，其日志行会在调用结束时一起到达，调用中途的沉默是正常的。
11. 在 follow 过程中重新部署是安全的：部署会在几秒内轮换脚本，同一个打开的流会在下次调用时投递新代码的日志行；不要每次部署后都拆掉流再重建。
12. `--since` 与 `--follow` 一起使用会被拒绝（流从现在开始），`--until` 和 `--order` 同样如此；需要历史数据就用一次性抓取。
13. 模式在启动时一次性决定：如果首次连接被拒绝或不可达，该次运行全程轮询；如果流成功打开，就没有轮询回退。
14. 运行中途丢失流会以 `Error: The realtime log stream stopped and could not be re-established` 结束命令并返回退出码 1；这个退出是流放弃，不是日志系统坏了的证据——重跑同一条命令，而不是改标志。
15. 先判断是调度运行还是请求：工作流是自动化系统（cron 调度、实体触发器、连接器事件、应用内 agent 动作）；当抱怨是“我的定时任务没跑”或“自动化停止工作”时，函数日志是错误工具，它只能显示函数打印了什么，无法告诉你运行是否被派发、其中哪个任务失败、或工作流为何停止触发。
16. 对调度问题运行 `npx base44 workflows runs --status failed` 和 `npx base44 workflows list`；失败的运行会带上失败的任务和底层错误，先从这里入手，等知道失败任务调用了哪个函数后再进入 `base44 logs`；`workflows list` 会报告 `consecutiveFailures`，大于零就是需要关注的工作流。
17. 注意两个误导点：触发列中的 `manual` 并不表示有人点击了什么，它是运行在完全没有触发类型时被标记的值；测试运行也会被包含，在触发类型旁标记为 `(scheduled, test)`，你自己为验证而触发的运行也会出现在列表里。
18. 检查最近错误：先运行 `npx base44 logs --level error` 拉取所有函数的最新错误。
19. 下钻到特定函数：运行 `npx base44 logs --function <function_name> --level error`；若不在项目目录中，显式传入应用：`npx base44 logs --app-id app_123 --function <function_name> --level error`。
20. 注意 `--function` 过滤的是被打上标记的行：仍使用旧版按函数部署的应用会产生未打标记的行，因此过滤视图可能隐藏它们，这会在应用下次部署时自愈；如果过滤后结果为空，先去掉 `--function` 重跑，再下结论说没有日志。
21. 检查时间范围：用 `npx base44 logs --function <function_name> --since <start_time> --until <end_time>` 与用户报告的问题时间戳做关联。
22. 分析日志：查找输出中的堆栈跟踪和错误消息；检查时间戳以与用户报告的问题关联；显式传入 `--limit` 以回溯更远，因为没有默认分页大小，且大于 500 的值会被截断为 500。
23. 正确解读空结果：`No logs found matching the filters.` 是有歧义的，绝不能读作“健康”；它意味着以下之一：运行尚未被摄取（最常见，等待并重跑）；没有该名称的函数，或过滤器丢掉了未打标记的行；读取 `--env prod` 时应用尚未发布（`No production logs found.`，可尝试 `--env preview` 查看草稿日志）。

适用边界 · 注意事项

• 当问题是“定时任务没跑”或“自动化停止工作”时，不要用函数日志，应改用工作流运行历史。
• 不要在刚触发函数后因一次性抓取返回空结果就断定没有日志或系统故障，索引摄取有约 20-30 秒延迟。
• 不要在 `--follow` 时使用 `--since`、`--until` 或 `--order`，这些参数会被拒绝。