调试
本指南介绍 AdonisJS 应用的调试技术。你将学习如何：
- 配置 VSCode 通过断点调试你的应用
- 从命令行使用 Node.js 检查器
- 使用
NODE_DEBUG查看框架级别的调试日志 - 使用 Edge 模板中的
@dump和@dd检查变量 - 在开发期间启用精美的错误页面
概述
调试是开发中必不可少的一部分，AdonisJS 支持根据你的需求采用多种方法。对于快速检查，一个简单的 console.log 语句通常就足够了。对于更复杂的问题，你可以使用 VSCode 集成的调试器设置断点、逐步执行代码并检查变量。当你需要了解框架内部发生的情况时，调试日志可以让你看到 AdonisJS 的内部运作。
Edge 模板有自己的调试工具 @dump 和 @dd，它们会直接在浏览器中渲染变量的内容。在开发期间，当发生问题时，异常处理器会自动显示带有堆栈跟踪和请求信息的详细错误页面。
VSCode 调试器
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>/**"]
},
{
"type": "node",
"request": "launch",
"name": "Tests",
"program": "${workspaceFolder}/ace.js",
"args": ["test", "--watch"],
"skipFiles": ["<node_internals>/**"]
},
{
"type": "node",
"request": "attach",
"name": "Attach Program",
"port": 9229,
"autoAttachChildProcesses": true,
"skipFiles": ["<node_internals>/**"]
}
]
}Dev server 配置以启用 HMR 的方式启动你的应用，非常适合调试 HTTP 请求处理、中间件和控制器。Tests 配置以监视模式运行你的测试套件，允许你通过在测试文件或应用代码中设置断点来调试失败的测试。
调试 Ace 命令
Attach Program
配置使用附加模式，而不是启动特定的命令。这让你可以调试任何 Ace 命令——使用 --inspect 标志启动它，然后附加调试器。
要调试 Ace 命令：
- 使用
Cmd+Shift+P（macOS）或Ctrl+Shift+P（Windows/Linux）打开命令面板 - 搜索 Debug: Select and Start Debugging
- 选择 Attach Program 选项
- 使用
--inspect标志运行你的 Ace 命令。
node --inspect ace migration:run调试器会附加到正在运行的进程，你的断点会被命中。
Node.js 检查器
如果你没有使用 VSCode，或者更喜欢不同的调试界面，你可以直接使用 Node.js 检查器。使用 --inspect 标志启动你的开发服务器。
node ace --inspect serve --hmr这会在端口 9229 上启动 Node.js 检查器。然后你可以通过在 Chrome 中导航到 chrome://inspect 使用 Chrome DevTools 连接，或者使用任何其他支持 Node.js 检查器协议的调试器。
框架调试日志
AdonisJS 包包含调试日志，可让你了解框架内部的情况。这些日志默认是禁用的，因为它们非常冗长，但当你需要了解框架层面发生的情况时，它们非常有价值。
在启动应用时，通过设置 NODE_DEBUG 环境变量来启用调试日志。
NODE_DEBUG=adonisjs:* node ace serve --hmr通配符 * 启用所有 AdonisJS 包的日志。如果你已经知道要调查哪个包，可以直接指定它以减少噪音。
# 仅调试 HTTP 层
NODE_DEBUG=adonisjs:http node ace serve --hmr
# 调试会话处理
NODE_DEBUG=adonisjs:session node ace serve --hmr
# 调试应用生命周期
NODE_DEBUG=adonisjs:app node ace serve --hmr包名遵循 adonisjs:<package-name> 的约定，其中包名对应于你想要调试的 AdonisJS 包。
Edge 模板调试
使用 Edge 模板时，你可以使用 @dump 和 @dd 在浏览器中直接检查变量。这些标签会渲染任何值的格式化表示，让你轻松理解模板接收到了哪些数据。
@dump 标签
@dump 标签输出一个值的格式化表示，并继续渲染模板的其余部分：
{{-- 检查组件属性 --}}
@dump($props.all())
{{-- 检查整个模板状态 --}}
@dump(state)
{{-- 检查特定变量 --}}
@dump(post)@dd 标签
@dd 标签（dump and die）会立即停止模板渲染，并且只显示被 dump 的值。当你想专注于某个特定值而不需要页面其余输出时，请使用它：
@dd(post)
{{-- 这一行以下的内容都不会渲染 --}}
<h1>{{ post.title }}</h1>设置 dumper
@dump 和 @dd 标签需要加载 dumper 的前端资源。将 @stack('dumper') 指令添加到你布局的 <head> 部分。
<!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>
@!section('content')
</body>
</html>官方的 AdonisJS 起步套件默认包含此设置。
配置 dumper
你可以通过从 config/app.ts 导出一个 dumper 配置来自定义 dumper 格式化输出的方式。
import { defineConfig as dumperConfig } from '@adonisjs/core/dumper'
export const dumper = dumperConfig({
/**
* 控制台输出设置（例如 console.log）
*/
console: {
depth: 10,
collapse: ['DateTime', 'Date'],
inspectStaticMembers: true,
},
/**
* HTML 输出设置（@dump 和 @dd）
*/
html: {
depth: 10,
inspectStaticMembers: true,
},
})console 和 html 打印机都可以使用以下选项。
showHidden
包含不可枚举的属性
depth
嵌套结构（对象、数组、映射、集合）的最大深度
inspectObjectPrototype
包含原型属性。设置为 true 表示所有对象，false 表示都不包含，或 'unless-plain-object' 表示仅类实例。
inspectArrayPrototype
包含数组原型属性
inspectStaticMembers
包含类的静态成员
maxArrayLength
数组、映射和集合显示的最大项数
maxStringLength
字符串显示的最大字符数
collapse
不应进一步展开的构造函数名称数组
异常处理器调试模式
在开发期间，当发生未处理的异常时，AdonisJS 会显示由 Youch 提供支持的 详细错误页面 。这些页面包含完整的堆栈跟踪、请求信息和应用状态，使诊断问题变得容易。
调试模式在开发环境中自动启用，在生产环境中禁用。此行为由异常处理器配置控制。