base44-troubleshooter

排查生产问题

前置条件

获取日志前，请确认已完成身份验证：

npx base44 whoami

如果尚未完成身份验证或令牌已过期，请告知用户运行 npx base44 login。

通过以下任一方式解析应用上下文：

# From a linked local project
cat base44/.app.jsonc

# Or explicitly
npx base44 logs --app-id app_123

可用命令

命令	描述	参考
base44 logs	获取此应用的函数日志	project-logs.md
base44 workflows runs	按时间倒序列出工作流运行记录；失败的运行会显示失败任务和底层错误	workflows-runs.md
base44 workflows list	列出此应用的工作流及其状态和运行摘要	workflows-list.md

日志不支持写后即读

单次获取未找到你的运行记录，并不能说明任何问题。 单次运行 base44 logs 会读取有延迟的索引，因此刚触发函数后结果为空是预期情况，并非问题证据。

• 实时调试：使用 --follow。 如果实时流可用，它会在一秒内传送日志行。如果不可用，CLI 会说明并改用轮询（Warning: Realtime logs are not available for this app — falling back to polling (lines may lag ~20-30s).）。无论哪种情况，--follow 都是正确工具——无需自行选择。
• 单次获取会延迟约 20-30 秒。 这是数据摄取所需的时间，不是筛选器的问题。
• 输出为空时，应调整的变量是时间，而不是标志。 等待后重运行相同的命令。增大 --limit、移除 --level 或切换 --order，都无法改变尚未摄取的日志行；反复调整标志会让 Agent 得出错误诊断。

故障排查流程

1. 实时观察 — --follow

如果你可以触发故障（或故障正在发生），请从这里开始，而不是事后获取日志：

npx base44 logs --follow
npx base44 logs --follow --function <function_name>

然后调用函数并读取传入的日志。遵循以下规则，避免误判正常的日志流：

• 切勿按计时器作出判断。 打开日志流，触发函数，然后持续读取，直到看到日志行——不要只读取固定时间窗口、打印结果，就断定“出故障了”。日志流暂时安静，是因为没有调用函数。
• 日志按调用传送，而非逐行传送。 长时间运行的函数产生的所有日志行，都会在调用结束时传送。调用过程中没有日志是正常的。
• 跟随日志时重新部署是安全的。 部署会在几秒内轮换脚本，同一条已打开的日志流会在下一次调用时传送新代码的日志。每次部署后都不必关闭并重建日志流。
• --follow 不接受 --since（日志流从当前时刻开始），也不接受 --until 和 --order。如需查看历史日志，请使用单次获取。
• 模式只在启动时决定一次。 如果首次连接被拒绝或无法访问，整个运行过程都会使用轮询。如果日志流成功打开，就不会再回退到轮询。
• 运行中日志流丢失会导致命令结束，并显示 Error: The realtime log stream stopped and could not be re-established，退出代码为 1。退出表示日志流已放弃连接，并不能证明日志记录出现故障——请重新运行相同的命令，而不是更改标志。

2. 确认这是否是计划运行，而非请求

工作流是自动化系统，包括 cron 计划、实体触发器、连接器事件和应用内 Agent 操作。**如果反馈是“我的计划任务没有运行”或“自动化停止工作”，函数日志就不是合适的工具。**日志会显示函数输出了什么，却无法告诉你是否派发了运行、其中哪个任务失败，或工作流为何不再触发。

npx base44 workflows runs --status failed
npx base44 workflows list

失败的运行会记录失败任务及底层错误，因此应从这里开始；只有确定失败任务调用了哪个函数后，才查看 base44 logs。 workflows list 会报告 consecutiveFailures——任何大于零的值都表示该工作流需要处理。

有两点容易造成误解：

• 触发器列中的 manual 并不意味着有人点击了什么。 如果派发运行时没有任何触发器类型，运行就会被标记为此值。
• 测试运行也会包含在内，并在触发器类型旁标记为 (scheduled, test)。你为检查某事而自行触发的运行也会显示在列表中。

3. 检查最近的错误

先提取所有函数中的最新错误：

npx base44 logs --level error

4. 深入检查特定函数

如果你知道哪个函数出现故障：

npx base44 logs --function <function_name> --level error

如果你不在项目目录中，请显式传入应用：

npx base44 logs --app-id app_123 --function <function_name> --level error

--function 筛选器只筛选带有标记的行。仍采用旧版逐函数部署方式的应用会生成未标记的行，因此筛选视图可能会将其隐藏；应用下次部署后会自动修复。如果筛选结果为空，请在得出没有日志的结论之前，不带 --function 重新运行。

5. 检查时间范围

将日志与用户报告的问题时间戳关联起来：

npx base44 logs --function <function_name> --since <start_time> --until <end_time>

6. 分析日志

• 在输出中查找堆栈跟踪和错误消息
• 检查时间戳，以便与用户报告的问题关联
• 显式传入 --limit，以查看更多历史记录——默认没有页大小，超过 500 的值会被限制为 500

读取空结果

No logs found matching the filters. 含义不明确——绝不能将其理解为“运行正常”。它可能表示：

• 运行尚未被采集（最常见——等待后重新运行，见上文）
• 不存在该名称的函数，或者筛选器排除了未标记的行（见步骤 3）
• 读取 --env prod 时，应用尚未发布（No production logs found.——尝试使用 --env preview 查看草稿日志）