meteor-debugging

调试 Meteor 应用

在改变行为之前，先找到第一个失败边界。生成稳定的复现步骤、能够支持某个原因的证据，以及验证目标。然后使用负责修复的技能。

诊断流程

1. 记录准确的症状、完整的错误和堆栈、命令或用户操作、Meteor 版本、解析后的 Atmosphere 和 npm 版本、环境，以及最后一次已知正常状态。
2. 编辑之前，使用范围最小且稳定的命令或操作复现问题。
3. 使用下表对第一个不确定边界进行分类。
4. 添加检测信息之前，先查看已有证据。比较客户端和服务端输出、近期变更，以及正常与失败环境之间的差异。
5. 只有在现有证据无法回答问题时，才添加一项有针对性的观察。不要将诊断变更与推测性修复结合起来。
6. 提出一个可证伪的假设，并指出什么观察结果会否定它。
7. 每次只更改一个变量，然后复现问题，并从错误值或事件向前追溯到其来源。
8. 通过负责修复的技能解决已确认的原因。如果问题可能再次发生，则在最低且可靠的层级添加回归测试。
9. 重新运行针对性的复现步骤，然后运行受影响的测试套件或类生产环境检查。移除临时诊断信息和产物。

如果多个有证据支持的假设都不成立，请重新检查边界图和假设，再叠加缓解措施或扩大变更范围。

选择边界

症状	首要证据	查看
构建卡住、编译错误、重建回归，或 Rspack、SWC 故障	完整构建输出、--verbose、准确的版本和构建包版本	构建调试
服务端在启动前崩溃，或在方法、发布、任务或钩子中失败	最早的服务端堆栈、启动顺序、与请求关联的证据	运行时和检查器
客户端堆栈、渲染过时、响应式循环，或客户端与服务端不一致	浏览器堆栈、渲染状态、响应式失效信息、服务端对比	运行时和检查器，然后查看 React 或 Blaze 技能
缺少文档、订阅卡住、重新连接，或代理/WebSocket 症状	服务端查询、发布输出、DDP 状态、订阅就绪状态、Minimongo	DDP 和数据
当前输出无法区分入口、守卫、分支、状态变化或事件顺序	少量经过脱敏的边界观察记录	日志和检测
Meteor Mocha 失败、仅在测试套件中失败、异步偶发故障，或浏览器 E2E 测试失败	完整钩子输出、客户端/服务端测试数量、现有报告和跟踪记录	测试和浏览器
Cordova 或 HCP 问题、仅在设备上发生的故障，或线上事故	设备日志和版本；部署日志、运行状况、指标、版本差异	移动端和生产环境

语法错误需要查看其堆栈，而不是追踪浏览器。仅在浏览器出现的水合竞态需要客户端证据，而不是服务端检查器。使用能够否定当前假设的最小工具。

证据规则

• 在临时日志中标明运行时端和操作。只有并发流程可能交错时，才记录请求或事件标识符。
• 仅记录经过筛选和脱敏的字段。绝不记录凭据、令牌、Cookie、授权标头、私有设置、未受限的方法参数或完整用户文档。
• 将 console.log 视为临时调试手段。对于必须持久保存的证据，请使用 meteor/logging 或应用程序既有的结构化日志记录器。
• 对于 Meteor 3.6-beta.1 至 beta.3 的服务端生命周期证据，请通过 日志与插桩 使用可选的 instrumentation 包。更早版本继续使用有针对性的日志；监听器用于观察，不用于授权。
• 仅当测试运行器和执行模式支持时，才将 .only 用作临时的本地测试聚焦。交接前请移除它，并运行更广泛的测试套件。
• 优先使用可观察的就绪状态，而非等待固定时长：订阅就绪、方法执行完毕、预期文档出现、UI 可见，或特定浏览器事件发生。
• 启动交互式浏览器之前，先检查现有的 Playwright 报告和跟踪记录。对于 playwright-cli 请求，请先确认可执行文件是否可用。如果不可用，请在安装或下载浏览器前获得授权。明确报告可用性检查结果并请求授权，而不是只询问应用 URL。仅在确实需要跨越浏览器边界时使用它。
• 对于经授权的临时 playwright-cli 复现：必须运行 snapshot、console 和 requests，在失败操作前开始跟踪，操作后立即停止跟踪，并关闭浏览器会话。不得以源码检查代替浏览器证据，也不得因为控制台或网络信息已暗示原因就省略跟踪。
• 仅使用用户明确纳入范围的应用路径或 URL。如果当前工作区没有应用，且提示中未提供 URL，请向用户索取。不要扫描无关目录、进程或端口来查找应用。
• 修改数据前，先通过 meteor shell 和 meteor mongo 读取数据。绝不可将 meteor reset --db 用作诊断捷径。
• 在生产环境中，不得暴露检查器、部署调试构建、保留包含机密的跟踪记录，或在实时数据上进行实验。

交接

已确认原因	后续处理
测试设置、设计、驱动程序、测试夹具或新的回归测试结构	meteor-testing
SWC、Rspack、监视器、缓存、构建图或生成的交接内容	meteor-modern-build-stack 或 migrate-to-rspack
已确认的 Cordova 平台、原生插件／配置、设备网络、签名或原生 HCP 兼容性	meteor-native
方法、发布、Mongo／Minimongo、React、Blaze、账户或安全性	对应的领域技能
Galaxy、容器、代理、环境、健康检查或发布	meteor-deployment
有文档记录的社区软件包行为	meteor-community-packages，然后查阅上游仓库
无 Meteor 边界的纯 Node.js、浏览器、数据库或运行器故障	通用调试指南

清理

交接前：

1. 仅移除为此次调查添加的日志、debugger 语句、.only 标记、暂停、临时路由和调试设置。
2. 根据数据敏感性，删除或妥善保护截图、跟踪记录、性能分析文件、已保存的浏览器状态和转储文件。
3. 重新运行原始复现步骤和受影响的测试套件。
4. 报告已确认的原因、证据、修复、验证结果以及任何尚存的不确定性。

反模式

• 在检查设置、异步完成情况以及被跳过的客户端覆盖范围之前，就修改断言。
• 没有明确假设，就在整个应用中添加日志。
• 不加区分地序列化所有运行时对象。循环引用的值、响应式包装器、getter、二进制数据和大型文档都需要有选择地创建快照。
• 即使整个测试套件仍然失败，也把单个聚焦测试通过视为成功。
• 不断添加任意休眠、宽泛选择器、重试或增加堆内存，直到症状消失。
• 对服务器、构建或数据库故障安装浏览器工具，或搭建测试脚手架。

参考资料

• 运行时和检查器
• 日志和插桩
• 测试和浏览器
• 构建调试
• DDP 和数据
• 移动端和生产环境
• 评估案例