meteor-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debug Meteor applications

调试Meteor应用

Find the first failing boundary before changing behavior. Produce a stable reproduction, evidence for one cause, and a verification target. Then use the skill that owns the repair.

在修改应用行为前，先定位第一个出现故障的边界。生成稳定的复现步骤、单一问题根源的证据以及验证目标，之后交由负责修复的技能处理。

Diagnosis loop

诊断流程

Record the exact symptom, complete error and stack, command or user action, Meteor release, resolved Atmosphere and npm versions, environment, and last known working state.
Reproduce with the narrowest stable command or action before editing.
Classify the first uncertain boundary with the table below.
Read existing evidence before adding instrumentation. Compare client and server output, recent changes, and passing versus failing environments.
Add one targeted observation only when current evidence cannot answer the question. Do not combine a diagnostic change with a speculative fix.
State one falsifiable hypothesis and the observation that would reject it.
Change one variable, reproduce, and trace a bad value or event backward to its origin.
Fix the confirmed cause through the owning skill. Add a regression at the lowest reliable layer when the failure can recur.
Re-run the focused reproduction, then the affected suite or production-like check. Remove temporary diagnostics and artifacts.

If several evidence-backed hypotheses fail, revisit the boundary map and assumptions before stacking mitigations or widening the change.

记录确切的症状、完整的错误信息与堆栈跟踪、触发命令或用户操作、Meteor版本、已解析的Atmosphere和npm包版本、运行环境，以及最后一次已知的正常工作状态。
在进行代码编辑前，用最精简的稳定命令或操作复现故障。
参照下方表格对第一个不确定的边界进行分类。
在添加监控工具前，先查看已有证据。对比客户端与服务器输出、近期代码变更，以及正常环境与故障环境的差异。
仅当现有证据无法解答问题时，才添加一项针对性的观测。不要同时进行诊断性修改和推测性修复。
提出一个可证伪的假设，以及能推翻该假设的观测结果。
更改一个变量，复现故障，并反向追踪异常值或事件的来源。
通过对应领域的技能修复已确认的问题根源。若故障可能再次发生，在最可靠的底层添加回归测试。
重新运行聚焦的复现步骤，然后执行受影响的测试套件或类生产环境检查。移除临时诊断工具和生成的文件。

若多个有证据支持的假设均不成立，在叠加缓解措施或扩大修改范围前，重新审视边界映射和已有假设。

Select the boundary

选择边界

Symptom	First evidence	Read
Build stalls, compilation error, rebuild regression, Rspack or SWC failure	Full build output, `--verbose` , exact release and build-package versions	Build debugging
Server crashes before startup or fails in a method, publication, job, or hook	Earliest server stack, startup order, request-correlated evidence	Runtime and inspector
Client stack, stale render, reactive loop, or client/server disagreement	Browser stack, rendered state, reactive invalidation, server comparison	Runtime and inspector, then the React or Blaze skill
Missing documents, stuck subscription, reconnect, or proxy/WebSocket symptom	Server query, publication output, DDP state, subscription readiness, Minimongo	DDP and data
Current output cannot distinguish an entry, guard, branch, state change, or event order	A small set of redacted boundary observations	Logs and instrumentation
Meteor Mocha failure, suite-only failure, async flake, or browser E2E failure	Full hook output, client/server test counts, existing report and trace	Tests and browser
Cordova or HCP problem, device-only failure, or live incident	Device logs and versions; deployment logs, health, metrics, release diff	Mobile and production

A syntax error needs its stack, not browser tracing. A browser-only hydration race needs client evidence, not a server inspector. Use the smallest tool that can reject the current hypothesis.

症状	首要证据	参考文档
构建停滞、编译错误、重建回归、Rspack或SWC失败	完整构建输出、 `--verbose` 日志、确切的版本号和构建包版本	构建调试
服务器启动前崩溃，或在方法、发布任务、定时任务或钩子中失败	最早的服务器堆栈跟踪、启动顺序、与请求相关的证据	运行时与调试器
客户端堆栈跟踪、渲染过时、响应式循环异常、或客户端与服务器数据不一致	浏览器堆栈跟踪、渲染状态、响应式失效信息、服务器数据对比	运行时与调试器，之后使用React或Blaze技能
文档缺失、订阅卡住、重连失败、或代理/WebSocket相关症状	服务器查询结果、发布输出、DDP状态、订阅就绪状态、Minimongo数据	DDP与数据
当前输出无法区分入口、守卫、分支、状态变化或事件顺序	一组经过编辑的边界观测数据	日志与监控
Meteor Mocha测试失败、仅套件失败、异步测试不稳定、或浏览器端E2E测试失败	完整钩子输出、客户端/服务器测试计数、已有报告与追踪信息	测试与浏览器
Cordova或HCP问题、仅设备端故障、或线上事件	设备日志与版本；部署日志、健康状态、指标、版本差异	移动与生产环境

语法错误只需要查看堆栈跟踪，不需要浏览器追踪。仅浏览器端的 hydration 竞争问题需要客户端证据，而非服务器调试器。使用能推翻当前假设的最小工具即可。

Evidence rules

证据规则

Label runtime side and operation in temporary logs. Include a request or event identifier only when concurrent flows can interleave.
Record selected, redacted fields. Never log credentials, tokens, cookies, authorization headers, private settings, unrestricted method arguments, or full user documents.
Treat
```
console.log
```
as temporary instrumentation. Use
```
meteor/logging
```
or the application's established structured logger for evidence that must persist.
Use
```
.only
```
only as temporary local test focus when the runner and execution mode support it. Remove it and run the broader suite before handoff.
Prefer observable readiness over sleeps: subscription ready, settled method, expected document, visible UI, or a specific browser event.
Inspect existing Playwright reports and traces before starting an interactive browser. For a
```
playwright-cli
```
request, first check whether the executable is available. If it is unavailable, obtain authority before installation or browser downloads. Explicitly report that availability result and request the authority rather than only asking for the application URL. Use it only for a real browser boundary.
For an authorized ad hoc
```
playwright-cli
```
reproduction: MUST run
```
snapshot
```
,
```
console
```
, and
```
requests
```
, start tracing before the failing action, stop tracing immediately after it, and close the browser session. Do not substitute source inspection for this browser evidence or omit the trace because the console or network already suggests a cause.
Use only an application path or URL the user placed in scope. If the current workspace has no app and the prompt gives no URL, ask for one. Do not scan unrelated directories, processes, or ports to discover an application.
Read through
```
meteor shell
```
and
```
meteor mongo
```
before mutating. Never use
```
meteor reset --db
```
as a diagnostic shortcut.
On production, do not expose an inspector, deploy a debug build, retain secret-bearing traces, or experiment on live data.

在临时日志中标记运行时端和操作类型。仅当并发流程可能交错时，才添加请求或事件标识符。
记录经过筛选和编辑的字段。切勿记录凭据、令牌、Cookie、授权头、私有配置、未受限的方法参数或完整用户文档。
将
```
console.log
```
视为临时监控工具。如需持久化证据，请使用
```
meteor/logging
```
或应用已有的结构化日志工具。
仅当测试运行器和执行模式支持时，才将
```
.only
```
作为临时本地测试聚焦标记。移交工作前，移除该标记并运行更完整的测试套件。
优先使用可观测的就绪状态而非休眠等待：订阅就绪、方法执行完成、预期文档出现、UI可见，或特定浏览器事件。
在启动交互式浏览器前，先查看已有的Playwright报告和追踪信息。对于
```
playwright-cli
```
请求，首先检查该可执行文件是否可用。若不可用，在安装或下载浏览器前需获得权限。明确报告可用性结果并请求权限，而非仅询问应用URL。仅在真实浏览器边界场景下使用该工具。
对于已授权的临时
```
playwright-cli
```
复现：必须运行
```
snapshot
```
、
```
console
```
和
```
requests
```
命令，在故障操作前启动追踪，故障操作后立即停止追踪，并关闭浏览器会话。切勿用源代码检查替代浏览器证据，也不要因为控制台或网络信息已暗示问题根源就省略追踪步骤。
仅使用用户指定范围的应用路径或URL。若当前工作区无应用且提示未提供URL，请向用户索要。不要扫描无关目录、进程或端口来查找应用。
在修改数据前，先查看
```
meteor shell
```
和
```
meteor mongo
```
的内容。切勿将
```
meteor reset --db
```
作为诊断捷径。
在生产环境中，不要暴露调试器、部署调试构建版本、保留含敏感信息的追踪数据，或在真实数据上进行实验。

Handoffs

移交规则

Confirmed cause	Continue with
Test setup, design, driver, fixture, or new regression structure	`meteor-testing`
SWC, Rspack, watcher, cache, build graph, or generated handoff	`meteor-modern-build-stack` or `migrate-to-rspack`
Method, publication, Mongo/Minimongo, React, Blaze, accounts, or security	Matching domain skill
Galaxy, container, proxy, environment, health check, or rollout	`meteor-deployment`
Documented community package behavior	`meteor-community-packages` , then the upstream repository
Pure Node.js, browser, database, or runner failure with no Meteor boundary	General debugging guidance

已确认的问题根源	后续处理技能
测试配置、设计、驱动、测试夹具或新的回归测试结构	`meteor-testing`
SWC、Rspack、监视器、缓存、构建图谱或生成的移交问题	`meteor-modern-build-stack` 或 `migrate-to-rspack`
方法、发布任务、Mongo/Minimongo、React、Blaze、账户系统或安全问题	对应领域技能
Galaxy、容器、代理、环境、健康检查或版本发布问题	`meteor-deployment`
已文档化的社区包行为问题	`meteor-community-packages` ，之后提交至上游仓库
纯Node.js、浏览器、数据库或运行器故障，且无Meteor边界相关问题	通用调试指南

Cleanup

清理工作

Before handoff:

Remove only the logs,
```
debugger
```
statements,
```
.only
```
markers, pauses, temporary routes, and debug settings added for this investigation.
Delete or protect screenshots, traces, profiles, saved browser state, and dumps according to their data sensitivity.
Re-run the original reproduction and the affected suite.
Report the confirmed cause, evidence, fix, verification, and any remaining uncertainty.

移交前需完成：

移除本次调查中添加的日志、
```
debugger
```
语句、
```
.only
```
标记、暂停点、临时路由和调试配置。
根据数据敏感性，删除或保护截图、追踪数据、性能分析报告、保存的浏览器状态和数据转储文件。
重新运行原始复现步骤和受影响的测试套件。
报告已确认的问题根源、证据、修复方案、验证结果以及任何剩余的不确定性。

Anti-patterns

反模式

Edit the assertion before checking setup, async completion, and skipped client coverage.
Add logs across the application without a hypothesis.
Serialize every runtime object indiscriminately. Circular values, reactive wrappers, getters, binary data, and large documents need selected snapshots.
Treat a focused passing test as success when the suite still fails.
Add arbitrary sleeps, broad selectors, retries, or heap increases until the symptom disappears.
Install browser tooling or scaffold tests for a server, build, or database failure.

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

References

参考文档

Runtime and inspector
Logs and instrumentation
Tests and browser
Build debugging
DDP and data
Mobile and production
Evaluation cases

运行时与调试器
日志与监控
测试与浏览器
构建调试
DDP与数据
移动与生产环境
评估案例