ai-auto-web-debug
v1.0.2
Published
Static HTTP server that auto-injects browser console errors into server logs, for AI-assisted debugging.
Maintainers
chalecaoReadme
ai-auto-web-debug
让 AI 调试网页时，也能看到浏览器控制台的报错。
ai-auto-web-debug 是一个零依赖的静态 HTTP 服务。它在任意目录启动后，会自动向所有 HTML 页面注入一段客户端脚本，把浏览器里的 console.error / console.warn / window.onerror / unhandledrejection 实时回传到服务端日志。这样在命令行里跑着大模型调试时，模型就能像看到 HTTP 日志一样直接看到页面里抛出的报错。
特性
- 零依赖（只使用 Node 内置模块）
- 自动注入到 HTML
<head>末尾，使用标记防重复注入 - 捕获
console.error、console.warn、未捕获异常、未处理 Promise 拒绝 - 使用
navigator.sendBeacon发送，页面刷新 / 跳转时也不丢日志 - 错误日志带时间戳、级别、URL、行号、堆栈，并附带 ANSI 颜色
- 支持自定义端口、绑定地址、托管目录
安装
npm install -g ai-auto-web-debug使用
进入要调试的目录并启动：
cd /Users/Downloads/miniworld
webdebug或显式指定目录和端口：
webdebug ./ -p 8080
webdebug /Users/Downloads/miniworld -p 9000命令行选项：
webdebug [dir] [options]
dir 要托管的目录（默认：当前目录）
-p, --port 监听端口（默认：8080）
-h, --host 绑定地址（默认：127.0.0.1）
--no-open 不打印访问链接
-v, --version
--help启动后用浏览器打开 http://127.0.0.1:8080/，页面里的报错会立刻打印到终端：
2026-07-25T10:02:06.950Z [INFO] http://127.0.0.1:8080/
webdebug client installed
2026-07-25T10:02:06.959Z [ERROR] http://127.0.0.1:8080/
at http://127.0.0.1:8080/:0:0
Uncaught TypeError: Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../".
TypeError: Failed to resolve module specifier "three". Relative references must start with either "/", "./", or "../".按 Ctrl+C 停止。
工作原理
bin/webdebug.js解析参数并调用lib/server.js启动一个 Node 原生http服务。- 对所有
.html/.htm响应，读取文件后在</head>之前注入客户端脚本与标记<!-- http-bug-injected -->，避免重复注入。 - 客户端脚本 hook 浏览器 4 类错误信号，统一通过
navigator.sendBeacon（回退到fetch keepalive）发到POST /__http_bug_log__。 - 服务端把日志格式化成带颜色与堆栈的多行文本，写到 stdout。
不做什么
- 不做热更新 / 文件监听。需要改文件后刷新浏览器即可。
- 不做 HTTPS。需要 HTTPS 时请在前面套一层
ngrok/cloudflared。 - 不注入到
application/javascript文件里，避免影响模块导入顺序。错误仍会通过window.onerror等回传。
开发
仓库结构：
.
├── bin/
│ └── webdebug.js # CLI 入口
├── lib/
│ └── server.js # HTTP 服务 + 注入逻辑
└── package.json直接运行：
node ./bin/webdebug.js ./ -p 8080License
MIT