---

🚀 为什么选择 Node Network DevTools?

还在用 console.log 打印每一个请求和响应吗？Node Network DevTools 将浏览器“网络”面板的熟悉体验带到了 Node.js 后端。无论是在调试外部 API 调用、微服务还是 Next.js Server Actions，你都可以实时查看每一个细节。

✨ 特性

- 💎 类似 DevTools 的体验 - 熟悉的响应式 Web GUI，用于检查 Header、Payload 和 Response。
- 🔌 全能拦截 - 原生支持 http/https 模块以及现代的 fetch/undici (Node.js 18+)。
- 🛠️ 零侵入开发 - 只需一行代码或一个简单的 CLI 标志即可接入项目。
- 🖥️ 极简浏览器窗口 - 自动启动基于系统原生浏览器 (Chrome, Edge, 或 Chromium) 的紧凑 App 模式窗口。
- 🔗 智能请求追踪 - 利用 AsyncLocalStorage 自动关联同一业务流中的多个异步请求。
- 🛡️ 内置脱敏 - 自动隐藏 Authorization 和 Cookie 等敏感信息，保障安全。
- ⚡ 框架友好 - 无缝集成 Next.js, Express, Fastify 等主流框架。
- 📦 双模块支持 - 完美兼容 ESM 和 CommonJS。

📸 截图

$3

!Web GUI

🚀 快速开始

$3

``bash
npm install @mt0926/node-network-devtools

或

pnpm add @mt0926/node-network-devtools
`

> 注意: 无需安装 Puppeteer 等额外依赖！工具会自动检测并使用系统中已有的浏览器。

$3

在应用入口文件的最顶部调用 install()。

ESM:
`typescript
import { install } from '@mt0926/node-network-devtools';

await install(); // 确保在发送任何网络请求的 import 之前调用
`

CommonJS:
`javascript
const { install } = require('@mt0926/node-network-devtools');

(async () => {
await install();
})();
`

$3

如果你不想修改源代码，可以使用 Node.js 的命令行参数来注入工具。

ESM:
`bash
node --import @mt0926/node-network-devtools/register your-script.js
`

CommonJS:
`bash
node -r @mt0926/node-network-devtools/register your-script.js
`

🖥️ Web GUI

启动后，一个极简的浏览器窗口会自动打开并显示实时请求列表。

- 紧凑尺寸 (800x600)，方便分屏调试。
- 搜索与过滤 - 按 URL、方法或状态码筛选。
- 详情面板 - 查看 Header、Payload 和 Response。
- 深色/浅色模式支持。

如果需要手动访问，请在控制台输出中查找 URL：
🚀 Node Network DevTools GUI started at http://localhost:9229

$3

`bash

自定义窗口大小

NND_BROWSER_WIDTH=1024 NND_BROWSER_HEIGHT=768 node --import @mt0926/node-network-devtools/register your-script.js

自定义窗口标题

NND_BROWSER_TITLE="我的应用网络监控" node --import @mt0926/node-network-devtools/register your-script.js

指定 GUI 端口

NND_GUI_PORT=9230 node --import @mt0926/node-network-devtools/register your-script.js

指定 WebSocket 端口

NND_WS_PORT=9231 node --import @mt0926/node-network-devtools/register your-script.js

禁用 GUI

NND_GUI_ENABLED=false node --import @mt0926/node-network-devtools/register your-script.js

禁用自动打开浏览器

NND_AUTO_OPEN=false node --import @mt0926/node-network-devtools/register your-script.js
`

🔧 配置

$3

#### 核心设置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| NND_MAX_REQUESTS | 最大存储请求数 | 1000 |
| NND_MAX_BODY_SIZE | 最大 body 大小（字节） | 1048576 (1MB) |
| NND_INTERCEPT_HTTP | 拦截 http/https | true |
| NND_INTERCEPT_UNDICI | 拦截 undici/fetch | true |
| NND_REDACT_HEADERS | 要脱敏的头（逗号分隔） | authorization,cookie |

#### GUI 设置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| NND_GUI_ENABLED | 启用 GUI 服务器 | true |
| NND_GUI_PORT | GUI 服务器端口 | 自动 |
| NND_WS_PORT | WebSocket 端口 | 自动 |
| NND_AUTO_OPEN | 自动打开浏览器 | true |
| NND_BROWSER_WIDTH | 浏览器窗口宽度 | 800 |
| NND_BROWSER_HEIGHT | 浏览器窗口高度 | 600 |
| NND_BROWSER_TITLE | 浏览器窗口标题 | Node Network DevTools |

$3

`typescript
import { setConfig } from '@mt0926/node-network-devtools';

setConfig({
maxRequests: 500,
maxBodySize: 512 * 1024,
redactHeaders: ['authorization', 'cookie', 'x-api-key'],
guiEnabled: true,
autoOpen: false,
browserWindowSize: { width: 1024, height: 768 },
browserWindowTitle: '我的应用网络监控',
});
`

$3

重要：始终在生产环境中禁用此工具！

`typescript
// 根据环境条件安装
if (process.env.NODE_ENV === 'development') {
const { install } = await import('@mt0926/node-network-devtools');
await install();
}
`

或使用环境变量：

`bash

在生产环境中，禁用 GUI 和自动打开

NODE_ENV=production NND_GUI_ENABLED=false NND_AUTO_OPEN=false node your-app.js
`

🎯 框架集成

$3

1. 复制 templates/instrumentation.ts 到项目根目录
2. 在 next.config.js 中启用 instrumentation：

`javascript
module.exports = {
experimental: {
instrumentationHook: true,
},
};
`

3. 启动开发服务器：

`bash
npm run dev
`

或在 package.json 中配置：

`json
{
"scripts": {
"dev": "next dev"
}
}
`

注意：当 Next.js 加载 instrumentation hook 时，工具会自动启动。

$3

`typescript
import express from 'express';
import { install } from '@mt0926/node-network-devtools';

await install();

const app = express();
// 你的路由...
`

$3

适用于任何 Node.js 框架！只需在应用代码之前安装拦截器即可。

📚 API 参考

$3

`typescript
// 快速安装
import { install, startGUI, stopGUI } from '@mt0926/node-network-devtools';

// 配置
import { getConfig, setConfig, resetConfig } from '@mt0926/node-network-devtools';

// 请求存储
import { getRequestStore } from '@mt0926/node-network-devtools';

// 上下文追踪
import {
runWithTrace,
getCurrentTraceId,
generateTraceId
} from '@mt0926/node-network-devtools';

// 拦截器
import { HttpPatcher, UndiciPatcher } from '@mt0926/node-network-devtools';
`

$3

关联同一业务流程中的多个请求：

`typescript
import { runWithTrace, getRequestStore } from '@mt0926/node-network-devtools';

await runWithTrace('user-login', async () => {
// 这些请求会被关联到同一个 traceId
await fetch('https://api.example.com/auth');
await fetch('https://api.example.com/user');
});

// 查询关联的请求
const store = getRequestStore();
const requests = store.getByTraceId('user-login');
`

📖 示例

查看 examples 目录获取更多使用示例：

- basic-http - 基础 HTTP 请求监听
- fetch-api - Fetch API 监听
- request-tracing - 请求追踪
- express-server - Express 服务器示例
- programmatic-api - 编程式 API 使用
- nextjs-app - Next.js App Router 集成

🔬 工作原理

1. HTTP 拦截：使用 @mswjs/interceptors 拦截 http/https 模块请求
2. Undici 拦截：使用 Agent.compose() 注册拦截器捕获 fetch 请求
3. 上下文传递：使用 AsyncLocalStorage 在异步调用链中传递 TraceID
4. 事件桥接：将拦截的请求转发到 WebSocket 客户端以实现 GUI 实时更新
5. 原生浏览器启动：自动检测并启动系统中的浏览器 (Chrome/Edge/Chromium)，并以专用的 App 模式窗口运行。

🤝 贡献

欢迎贡献！请阅读我们的贡献指南了解详情。

$3

`bash

克隆仓库

git clone https://github.com/dong0926/node-network-devtools.git
cd node-network-devtools

安装依赖

pnpm install

构建项目

pnpm build

运行测试

pnpm test:all
``

📝 许可证

MIT © ddddd

🙏 致谢

- @mswjs/interceptors - HTTP 请求拦截
- undici - HTTP/1.1 客户端
- ws - WebSocket 实现
- puppeteer - 浏览器自动化

📮 支持

- 🐛 报告问题
- 💬 讨论
- 📧 邮箱：xx630133368@gmail.com

---