# 调试与编辑器配置

## VS Code 扩展

安装官方扩展 `denoland.vscode-deno`，然后在命令面板执行 **Deno: Initialize Workspace Configuration**。它会在工作区的 `.vscode/settings.json` 写入：

```json
{
  "deno.enable": true
}
```

- 只在工作区级启用，不要写进用户级设置，否则每个项目都会被当作 Deno 项目。
- 启用后扩展用 Deno 语言服务器接管，并关闭 VS Code 内置的 TS/JS 诊断。
- 混合仓库用 `deno.enablePaths` 只对子目录（如 `./supabase/functions`）启用。

其他编辑器通过 LSP 接入同一个语言服务器：

```bash
deno lsp
```

遇到异常先用命令面板的 **Deno: Language Server Status** 确认当前生效的配置。

## Inspector 断点调试

Deno 支持 V8 Inspector 协议，三个标志对应三种启动方式：

| 标志 | 行为 |
| --- | --- |
| `--inspect` | 启动调试服务端，代码立即执行 |
| `--inspect-wait` | 等待调试器连接后再执行 |
| `--inspect-brk` | 等待连接并在第一行断住 |

默认监听 `127.0.0.1:9229`。用 Chromium 内核浏览器打开 `chrome://inspect`，点击目标旁的 **Inspect** 即可断点、单步，并通过 sourcemap 直接看到原始 TypeScript。

VS Code 用 attach 配置连接：

```json title=".vscode/launch.json"
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to dev server",
      "type": "node",
      "request": "attach",
      "port": 9229
    }
  ]
}
```

```bash
deno run --inspect-wait --allow-net main.ts
```

<Callout type="warn" title="Inspector 监听地址保持 127.0.0.1">
暴露在可路由地址上的 Inspector 等价于远程任意代码执行。容器内调试通过端口转发或 exec 进入容器进行，不要把 `--inspect=0.0.0.0:9229` 带进生产镜像。
</Callout>

## 权限与泄漏排错

权限报错方向不明时，让运行时给出触发点的栈：

```bash
DENO_TRACE_PERMISSIONS=1 deno run main.ts
```

测试报资源或异步操作泄漏时，追踪泄漏来源：

```bash
deno test --trace-leaks
```

`--trace-leaks` 会拖慢测试执行，定位完就移除，不要常驻 CI。两个手段都只用于诊断，输出本身不包含修复方案。

## 日志分层

- 开发期用 `console.log` / `console.error`，它们走 stdout/stderr，容器平台天然收集。
- 生产日志输出结构化 JSON（每行一个对象，带 `level`、`msg`、`requestId` 字段），避免正则解析自由文本。
- Deno 运行时自身的诊断（模块解析、网络、权限决策）用 `--log-level=debug` 打开，定位问题后关闭；第三方库的日志等级由库自身配置控制，该 flag 管不到。
- 日志不包含密钥与个人数据；见[环境变量与 .env 管理](/docs/core/env-variables)。

官方参考：[Debugging](https://docs.deno.com/runtime/fundamentals/debugging/)、[VS Code](https://docs.deno.com/runtime/reference/vscode/)、[deno test](https://docs.deno.com/runtime/reference/cli/test/)。