@a-shui/remote-debug-sdk

前端监控 SDK — 支持 WebSocket 实时调试、HTTP 日志上报和 Sourcemap 上传。

安装

pnpm add @a-shui/remote-debug-sdk

接入方式

两种接入方式，按项目类型选择：

| 项目类型 | 接入方式 | 配置来源 | |---|---|---| | React / Vue / Next.js 等工程化项目 | npm 安装 + 环境变量 | .env | | 纯 HTML / CDN 引入 | <script> + 手动配置 | 代码里写 |

工程化项目（React / Vue / Next.js）

写一份 .remote-debug.config.js，加上对应框架的插件，SDK 和 CLI 自动读取——一处配置，不需要写 .env：

# 复制模板快速开始
cp node_modules/@a-shui/remote-debug-sdk/.remote-debug.config.example .remote-debug.config.js

// .remote-debug.config.js
export default {
  appId: 'demo',
  baseUrl: 'http://local.wz-inc.com:3000/reportmonitor',
  bufferSize: 40,
  debug: true,
};

Vite 项目 — 在 vite.config.ts 里加一行插件：

// vite.config.ts
import { remoteDebugVitePlugin } from '@a-shui/remote-debug-sdk/vite';

export default defineConfig({
  plugins: [remoteDebugVitePlugin()],
});

Next.js 项目 — 在 next.config.ts 里包装配置：

// next.config.ts
import { remoteDebugNextPlugin } from '@a-shui/remote-debug-sdk/next';

const nextConfig = { /* 你的 Next.js 配置 */ };
module.exports = remoteDebugNextPlugin(nextConfig);

业务代码只需传运行时值（userId）：

import sdk from '@a-shui/remote-debug-sdk';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // appId/baseUrl 从 .remote-debug.config.js 自动注入
    // 只需要传运行时才能确定的 userId
    sdk.init({ userId: currentUser.id });
  }, []);

  return <div>...</div>;
}

用户登录后更新 userId：

function onLogin(user) {
  sdk.setUserID(user.id);
}

CI 上传 sourcemap（同一份配置文件，CLI 也自动读取）：

- run: pnpm build
- run: pnpm exec remote-debug-sdk upload-sourcemaps ./dist
  env:
    REMOTE_DEBUG_RELEASE: ${{ github.sha }}

插件做的事：构建时读 .remote-debug.config.js，把 SDK 需要的字段注入到 import.meta.env（Vite）或 process.env.NEXT_PUBLIC_*（Next.js）。SDK 的 init() 已经内置了环境变量读取逻辑，所以配置自动生效，不需要手动写 .env。

纯 HTML / CDN 项目

手动在 <script> 里写配置：

<script src="https://your-cdn.com/remote-debug-sdk.min.js"></script>
<script>
  RemoteDebugSDK.init({
    appId: 'your-app-id',
    userId: 'user-123',
    baseUrl: 'https://your-monitor-server.com/reportmonitor',
    bufferSize: 40,
    debug: true
  });
</script>

SDK 配置项 (SDKConfig)

| 字段 | 类型 | 必填 | 默认值 | 说明 | |---|---|---|---|---| | appId | string | 是 | — | 应用 ID | | userId | string | 是 | — | 用户 ID，建议用登录 ID 或设备 ID | | baseUrl | string | 是 | — | 服务基础地址，自动推导 serverUrl/httpUrl/path | | serverUrl | string | 否 | 由 baseUrl 推导 | WebSocket 服务端地址（origin 部分） | | httpUrl | string | 否 | 由 baseUrl 推导 | HTTP 日志上报地址 | | path | string | 否 | 由 baseUrl 推导 | socket.io 路径 | | bufferSize | number | 否 | 20 | 环形队列容量 | | autoConnect | boolean | 否 | true | 是否自动连接 WebSocket | | enableHttpReport | boolean | 否 | true | 是否开启 HTTP 日志上报 | | reportTypes | string[] | 否 | ["error"] | 自动上报类型: debug/log/info/warn/error/http | | debug | boolean | 否 | false | 调试模式，控制台输出 SDK 日志 |

baseUrl 推导规则： 假设 baseUrl = "http://host:3000/reportmonitor"，则 serverUrl = "http://host:3000"，httpUrl = baseUrl，path = "/reportmonitor/socket.io"。如需覆盖某一项，可单独指定 serverUrl/httpUrl/path。

SDK 默认配置读取优先级

init() 传入的值  >  window.__REMOTE_DEBUG_CONFIG__  >  构建时环境变量

| 前缀 | 适用框架 | 示例 | |---|---|---| | VITE_REMOTE_DEBUG_* | Vite | VITE_REMOTE_DEBUG_APP_ID | | NEXT_PUBLIC_REMOTE_DEBUG_* | Next.js | NEXT_PUBLIC_REMOTE_DEBUG_APP_ID | | REMOTE_DEBUG_* | 通用 | REMOTE_DEBUG_APP_ID |

| 配置字段 | 环境变量名 | |---|---| | appId | REMOTE_DEBUG_APP_ID | | baseUrl | REMOTE_DEBUG_BASE_URL | | serverUrl | REMOTE_DEBUG_SERVER_URL | | httpUrl | REMOTE_DEBUG_HTTP_URL | | path | REMOTE_DEBUG_PATH | | bufferSize | REMOTE_DEBUG_BUFFER_SIZE | | debug | REMOTE_DEBUG_DEBUG |

CLI 命令

pnpm exec remote-debug-sdk <command>
# 或
npx remote-debug-sdk <command>

upload-sourcemaps

扫描 .map 文件并上传到 monitor 服务端，上传后默认删除 .map 文件。

remote-debug-sdk upload-sourcemaps [distDir] [options]

| 参数 | 默认值 | 说明 | |---|---|---| | [distDir] | ./dist 或配置文件 distDir | 要扫描的目录 | | --app-id <id> | 配置文件/env | 应用 ID | | --http-url <url> | 配置文件/env | monitor HTTP 地址（SDK 的 httpUrl） | | --release <version> | "default" | 版本号/部署标识 | | --include <patterns> | **/*.map | glob 规则，逗号分隔 | | --delete-map | true（默认行为） | 上传后删除 .map 文件 | | --no-delete-map | — | 上传后保留 .map 文件 | | --dry-run | false | 预演模式，只列文件不上传 | | -h, --help | — | 显示帮助 |

# 最简用法
pnpm exec remote-debug-sdk upload-sourcemaps ./dist

# CI 推荐：指定 release
pnpm exec remote-debug-sdk upload-sourcemaps ./dist --release v1.2.3

# 预演确认文件范围
pnpm exec remote-debug-sdk upload-sourcemaps ./dist --dry-run

# 上传后保留 .map 文件（本地调试用）
pnpm exec remote-debug-sdk upload-sourcemaps ./dist --no-delete-map

CLI 配置文件

CLI 从配置文件和环境变量读取默认值，减少每次手传 flag。

格式支持

JS 配置文件支持三种写法（选一种即可）：

// 写法 1: export default { ... }   (ESM，最常见)
// 写法 2: module.exports = { ... } (CJS，CommonJS 项目)
// 写法 3: 直接 { ... }             (最简洁，无需 export)

| 格式 | 文件名 | 适用场景 | |---|---|---| | JSON | .remote-debug.config.json | 纯静态配置 | | ESM | .remote-debug.config.js | 推荐，可写注释和 process.env | | CJS | .remote-debug.config.cjs | CommonJS 项目 | | MJS | .remote-debug.config.mjs | ESM 专用 |

查找优先级：.mjs > .cjs > .js > .json（找到第一个即停止）。

复制模板快速开始：

cp node_modules/@a-shui/remote-debug-sdk/.remote-debug.config.example .remote-debug.config.js

JS 格式示例（推荐）

// .remote-debug.config.js
export default {
  appId: process.env.REMOTE_DEBUG_APP_ID || 'demo',
  baseUrl: process.env.REMOTE_DEBUG_BASE_URL || 'http://local.wz-inc.com:3000/reportmonitor',
  release: process.env.REMOTE_DEBUG_RELEASE || 'default',
  distDir: './dist',
  include: ['**/*.map'],
  deleteMapAfterUpload: true,
};

或最简洁写法（去掉 export default）：

// .remote-debug.config.js
{
  appId: process.env.REMOTE_DEBUG_APP_ID || 'demo',
  baseUrl: process.env.REMOTE_DEBUG_BASE_URL || 'http://local.wz-inc.com:3000/reportmonitor',
  release: 'default',
  distDir: './dist',
  include: ['**/*.map'],
  deleteMapAfterUpload: true,
}

JSON 格式示例

{
  "appId": "demo",
  "baseUrl": "http://local.wz-inc.com:3000/reportmonitor",
  "release": "default",
  "distDir": "./dist",
  "include": ["**/*.map"],
  "deleteMapAfterUpload": true
}

配置文件字段

| 字段 | 说明 | |---|---| | appId | 应用 ID（CLI + SDK 共用） | | baseUrl | 服务基础地址（CLI + SDK 共用，自动推导 serverUrl/httpUrl/path） | | release | 版本号/部署标识，默认 "default" | | distDir | sourcemap 扫描目录，默认 ./dist | | include | glob 扫描规则，默认 ["**/*.map"] | | deleteMapAfterUpload | 上传后是否删除 .map 文件，默认 true | | httpUrl | HTTP 上报地址（可选，由 baseUrl 推导） | | serverUrl | WebSocket 地址（可选，由 baseUrl 推导） | | path | socket.io 路径（可选，由 baseUrl 推导） | | bufferSize | 环形队列容量（SDK 专用） | | debug | 调试模式（SDK 专用） |

CLI 配置优先级

CLI flag  >  环境变量  >  .env 文件  >  配置文件  >  package.json "remoteDebug" 字段

API

sdk.init(config: SDKConfig)

初始化 SDK。未传的字段自动从环境变量 / window.__REMOTE_DEBUG_CONFIG__ 读取。

// 最简用法 — baseUrl 自动推导 serverUrl/httpUrl/path
sdk.init({ appId: 'demo', userId: 'user1', baseUrl: 'http://host:3000/reportmonitor' });

// 只传运行时值（环境变量 / 配置文件自动填充其余字段）
sdk.init({ userId: currentUser.id });

sdk.setUserID(userId: string)

用户登录后更新用户标识，断开旧连接并用新 userId 重新连接。

sdk.report(level, category, message, content?, stack?)

手动上报自定义日志。

| 参数 | 类型 | 说明 | |---|---|---| | level | 1-5 | debug=1, log=2, info=3, warn=4, error=5 | | category | string | console / network / js_error | | message | string | 简述消息 | | content | string? | 详细内容 (JSON string) | | stack | string? | 错误堆栈 |

sdk.connect() / sdk.disconnect()

手动连接/断开 WebSocket。

sdk.is_connected(): boolean

检查是否已连接。

sdk.get_storage(): StorageData

获取当前页面的 cookies、localStorage、sessionStorage。

sdk.destroy()

销毁 SDK，释放所有资源。

功能说明

• Console 拦截 — 自动拦截 console.log/info/warn/error，存入环形队列，被监控时上报
• Network 拦截 — 拦截 XMLHttpRequest 和 Fetch API，超过 500KB 的 body 截断为 [Body Too Large]
• Error 捕获 — 自动捕获 window.onerror 和 unhandledrejection
• 环形队列 — 固定容量（默认 20 条），循环覆写，被监控时一次性上报历史数据
• URL 参数触发 — 添加 ?reportbug=1 自动触发调试模式

浏览器支持

Chrome >= 60 / Firefox >= 55 / Safari >= 12 / Edge >= 79

CLI 退出码

| 码 | 含义 | |---|---| | 0 | 成功 / dry-run 完成 / 没找到 .map 文件 | | 1 | 缺必填字段、目录不存在、HTTP 失败、未知 flag |