调试

在本指南中，我们将探索多种调试 AdonisJS 应用的方式，从使用 VSCode 调试器到使用 Dump and Die，以及查看框架的调试日志。

使用 VSCode 调试器调试

使用 VSCode 调试器调试 AdonisJS 应用非常简单。你只需创建一个 .vscode/launch.json 文件，并使用 Node.js 调试器即可。

在下面的示例中，我们定义一个配置，以调试模式启动 AdonisJS 开发服务器，然后将 VSCode 调试器附加到它上面。

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Dev server",
      "program": "${workspaceFolder}/ace.js",
      "args": ["serve", "--hmr"],
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

要开始调试：

使用 (CMD + Shift + P) 打开命令面板。
搜索 Debug: Select and Start Debugging。你会从 .vscode/launch.json 文件中找到一组启动选项。
选择 Dev server 选项以使用 VSCode 调试器运行 HTTP 服务器。

调试测试

你可以定义另一个启动选项，以调试模式运行测试。

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Dev server",
      "program": "${workspaceFolder}/ace.js",
      "args": ["serve", "--hmr"],
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Tests",
      "program": "${workspaceFolder}/ace.js",
      "args": ["test", "--watch"],
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

调试所有其他 Ace 命令

为每个 ace 命令定义单独的启动选项并不现实。因此，你可以在 .vscode/launch.json 文件中定义一个 attach 配置。

在 attach 模式下，VSCode 会将其调试器附加到一个已经运行的 Node.js 进程上，前提是该进程是从 VSCode 集成终端中使用 --inspect 标志启动的。

让我们先修改 .vscode/launch.json 文件，并向其中添加以下配置。

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach Program",
      "port": 9229,
      "autoAttachChildProcesses": true,
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Dev server",
      "program": "${workspaceFolder}/ace.js",
      "args": ["serve", "--hmr"],
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Tests",
      "program": "${workspaceFolder}/ace.js",
      "args": ["test", "--watch"],
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

要以 attach 模式开始调试：

使用 (CMD + Shift + P) 打开命令面板。
搜索 Debug: Select and Start Debugging。你会从 .vscode/launch.json 文件中找到一组启动选项。
选择 Attach Program 选项。
使用 --inspect 标志运行一个 Ace 命令。例如：
```
node --inspect ace migration:run
```

调试 Edge 模板

你可以像调试用 TypeScript 编写的应用代码一样调试 Edge 模板。不过，使用 Edge 时，你无法使用 VSCode 提供的断点。相反，你必须使用 @debugger 标签来定义代码内断点。

调试器会显示 Edge 模板的编译后输出。

@debugger

Dump and Die

Dump and Die（即 dd）类似于最受喜爱的调试技巧 console.log。不过，dd 辅助函数会通过抛出异常来暂停执行，并在浏览器或终端中显示输出。

在 HTTP 请求期间使用 dd 辅助函数时，输出会渲染为 HTML 文档。否则，输出会显示在终端中。

start/routes.ts

import User from '#models/user'
import router from '@adonisjs/core/services/router'
import { dd } from '@adonisjs/core/services/dumper'

router.get('/users', async () => {
  const users = await User.all()
  /**
   * 访问 "/users" 端点以查看 dump 的值
   */
  dd(users)
  return users
})

dd 的输出与你使用 console.log 时看到的略有不同。

你可以看到值被 dump 处的源代码位置。
你可以查看类的静态属性和对象的原型属性。
默认显示最多 10 层的嵌套值。
支持多种 HTML 输出主题。你可以在 nightOwl、catppuccin 和 minLight 之间选择。

用于调试的 Edge 辅助函数

你可以在 Edge 模板中通过 @dd 标签使用 dd 辅助函数。此外，你还可以使用 @dump 辅助函数，它不会抛出异常，并会继续渲染模板的其余部分。

{{-- Dump 模板状态并 die --}}
@dd(state)

{{-- Dump 模板状态并继续渲染 --}}
@dump(state)

使用 @dump 辅助函数时，请确保页面上有一个名为 "dumper" 的 EdgeJS Stack。@dump 辅助函数使用的脚本和样式会被写入这个 stack，以便包含在最终的 HTML 输出中。

<!DOCTYPE html>
  <html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    @stack('dumper')
  </head>
  <body>
    @dump(state)
  </body>
</html>

Dumper 设置

你可以在 config/app.ts 文件中配置 dumper 设置。该文件应导出一个 dumper 配置对象，如下所示。

config/app.ts

/**
 * "dd" 辅助函数使用的全局配置。你可以
 * 分别为 "console" 和 "html" 打印机配置设置。
 */
export const dumper = dumperConfig({
  /**
   * console 打印机的设置
   */
  console: {
    depth: 10,

    /**
     * 不应进一步展开的对象。该数组
     * 接受一组对象构造函数的名称。
     */
    collapse: ['DateTime', 'Date'],
    inspectStaticMembers: true,
  },

  /**
   * HTML 打印机的设置
   */
  html: {
    depth: 10,
    inspectStaticMembers: true,
  },
})

showHidden

设为 true 时，对象不可枚举的属性也会被处理。默认：false

depth

停止解析嵌套值的深度。该深度在所有树状数据结构中共享。例如，Objects、Arrays、Maps 和 Sets。默认：5

inspectObjectPrototype

检查对象的原型属性。原型的不可枚举属性默认包含在内。默认：'unless-plain-object'。

设为 true 时，所有对象的原型属性都会被处理。
设为 false 时，原型属性永远不会被处理。
设为 'unless-plain-object' 时，类实例的原型属性会被处理。

inspectArrayPrototype

检查 Array 的原型属性。默认：false。

inspectStaticMembers

检查类的静态成员。尽管函数和类在技术上是相同的，但此配置仅适用于使用 [class] 关键字定义的函数。默认：false。

maxArrayLength

要处理的 Arrays、Maps 和 Sets 的最大成员数。默认：100。

maxStringLength

要为字符串显示的最大字符数。默认：1000。

collapse

不应被进一步检查的对象构造函数名称数组。

框架调试日志

你可以使用 NODE_DEBUG 环境变量查看框架调试日志。NODE_DEBUG 标志受 Node.js 运行时支持，你可以使用它按模块名查看一个或多个模块的日志。

例如，你可以使用 NODE_DEBUG="adonisjs:*" 查看所有 AdonisJS 包的日志。

NODE_DEBUG="adonisjs:*" node ace serve --hmr

类似地，你可以使用 NODE_DEBUG 环境变量查看来自 Node.js 原生模块（如 fs、net、module 等）的日志。

NODE_DEBUG="adonisjs:*,net,fs" node ace serve --hmr

基础

异常处理

基础

Vite

调试

使用 VSCode 调试器调试

调试测试

调试所有其他 Ace 命令

调试 Edge 模板

Dump and Die

用于调试的 Edge 辅助函数

Dumper 设置

框架调试日志

On this page