探测模式

🌐 Probe mode

版本历史
版本变更
v26.2.0

JSON report schema bumped to v2. Probe target is now { suffix, line, column? } instead of an array. Each "hit" event carries a location field reporting the actual evaluation location. When the probe does not specify a column, it binds to the first executable column instead of defaulting to 1.

v26.1.0

新增于: v26.1.0

稳定性： 1 - 实验性

node inspect 支持通过标志 --probe 在应用中以非交互方式探测运行时值。

目前，探针模式仅支持从命令行指定的入口点脚本启动新进程。

🌐 Currently, probe mode only supports launching a new process from the entry point script specified on the command line.

探测模式会设置一个或多个源代码断点，每当执行到断点时评估指定的表达式，并在会话结束时（无论是正常完成、错误还是超时）打印所有已评估表达式的最终报告。这使开发者能够进行类似 printf 的调试，而无需修改应用代码并在之后进行清理。它还支持用于工具的结构化 JSON 输出。

🌐 The probe mode sets one or more source breakpoints, evaluates specified expressions whenever the execution reaches a breakpoint, and prints one final report of all the evaluated expressions when the session ends (either on normal completion, error, or timeout). This allows developers to perform printf-style debugging without having to modify the application code and clean up afterwards. It also supports structured JSON output for tool use.

$ node inspect --probe <file>:<line>[:<col>] --expr <expr>
              [--probe <file>:<line>[:<col>] --expr <expr> ...]
              [--json] [--preview] [--timeout=<ms>] [--port=<port>]
              [--] [<node-option> ...] <script> [<script-args> ...]
  • --probe <file>:<line>[:<col>]：探针的源位置。当执行到达该位置时，提供的表达式会被评估并打印在输出中。<file> 匹配要探测的脚本的 URL 后缀。<line> 和 <col> 的数字是从 1 开始计数的。当省略 <col> 时，探针绑定到该行的第一个可执行列。
  • --expr <expr>：JavaScript 表达式，在执行达到前面指定的 --probe 位置时进行评估。必须紧跟它所属的 --probe 之后。
  • --timeout=<ms>：整个探测会话的全局实时时钟截止时间。默认值为 30000。这可以用来探测可以被外部终止的长时间运行的应用。
  • --json：如果使用，将打印结构化的 JSON 报告，而不是默认的文本报告。
  • --preview：如果使用，非原始值将包括对象类 JSON 探针值的 CDP 属性预览。
  • --port=<port>：选择本地检查端口，探测会话将在该端口监听。默认为 0，表示请求一个随机端口。
  • -- 是可选的，除非子级需要它自己专用的 Node.js 标志。

--probe 和 --expr 参数的附加规则：

🌐 Additional rules about the --probe and --expr arguments:

  • --probe <file>:<line>[:<col>] 和 --expr <expr> 是严格配对的。每个 --probe 必须紧跟着正好一个 --expr。
  • --timeout、--json、--preview 和 --port 是整个探测会话的全局探测选项。它们可以出现在探测对之前或之间，但不能出现在 --probe 与其匹配的 --expr 之间。
  • 如果需要向子脚本传递额外的 Node.js 执行参数，必须使用 -- 将探针选项与子脚本的 Node.js 选项分开。

示例：

🌐 Example:

$ node inspect --probe app.js:10 --expr "user"
               --probe src/utils.js:5:15 --expr "config.options"
               --json --preview -- --no-warnings app.js --arg-for-app=foo