chengyi-frondend-monitor-sdk 1.0.0

package/README.md

@@ -0,0 +1,110 @@
+# Monitor SDK
+
+一个轻量级的前端错误监控 SDK，可以捕获 JavaScript 错误、Promise 异常、网络请求错误以及资源加载错误。
+
+## 功能特性
+
+- **JavaScript 错误监控**: 捕获未捕获的 JavaScript 错误 (`window.onerror`)。
+- **Promise 异常监控**: 捕获未处理的 Promise 拒绝 (`window.onunhandledrejection`)。
+- **网络错误监控**:
+  - 拦截并监控 `XMLHttpRequest` 错误。
+  - 拦截并监控 `fetch` API 错误。
+- **资源加载错误监控**: 捕获资源（如图片 `<img>` 和脚本 `<script>`）加载失败的错误。
+- **数据上报**: 优先使用 `navigator.sendBeacon` 进行可靠的数据上报，是一种在页面卸载或关闭时可靠发送数据的方法。
+
+## 安装
+
+```bash
+pnpm i chengyi-frondend-monitor-sdk
+```
+
+## 使用方法
+
+在你的应用入口文件（例如 `main.js` 或 `App.tsx`）中初始化 SDK。
+
+```javascript
+import { initErrorMonitor } from 'chengyi-frondend-monitor-sdk';
+
+initErrorMonitor({
+  reportUrl: 'https://', // 你的错误上报接口地址
+  projectName: 'oms', // 项目名称
+  environment: 'production',
+});
+```
+
+## 配置项
+
+`initErrorMonitor` 函数接受一个配置对象，包含以下属性：
+
+| 属性名        | 类型     | 说明                                                         |
+| ------------- | -------- | ------------------------------------------------------------ |
+| `reportUrl`   | `string` | **必填**。错误数据将通过 POST 请求发送到的 URL 地址。        |
+| `projectName` | `string` | **必填**。用于标识错误来源的项目名称。                       |
+| `environment` | `string` | **必填**。当前运行环境（例如 'production', 'development'）。 |
+
+## 请求项
+请求体示例
+
+- **`userId`** (可选)：用户 ID，用于关联用户相关错误。
+- **`errorType`**：错误类型，例如 `'JavaScript Error'`、`'Promise Rejection'` 等。
+- **`message`**：错误描述信息。
+- **`stack`** (可选)：错误的调用栈信息。
+- **`source`**：错误发生的资源 URL。
+- **`projectName`**：项目名称。
+- **`environment`**：当前运行环境。
+- **`userAgent`**：用户代理字符串。
+- **`resource`**：错误发生的资源 URL。
+- **`timestamp`**：错误发生的时间戳，ISO 格式字符串。
+
+| 属性名        | 类型     | 说明                                                         |
+| ------------- | -------- | ------------------------------------------------------------ |
+| `userId`      | `string` | 可选。用户 ID，用于关联错误数据到具体用户。                  |
+| `errorType`   | `string` | 可选。错误类型，例如 'JavaScript Error', 'Promise Rejection', 'Network Error', 'Resource Load Error', 'Vue Error'。 |
+| `message`     | `string` | 可选。错误描述信息。                                         |
+| `stack`       | `string` | 可选。错误的调用栈信息。                                     |
+| `source`      | `string` | 可选。错误发生的文件路径或 URL。                             |
+| `projectName` | `string` | 可选。项目名称，用于标识错误来源。                           |
+| `environment` | `string` | 可选。运行环境，例如 'production', 'development'。           |
+| `userAgent`   | `string` | 可选。用户代理字符串，用于标识客户端浏览器信息。           |
+| `resource`    | `string` | 可选。错误发生的资源 URL。                                   |
+| `timestamp`   | `string` | 可选。错误发生的时间戳，ISO 格式字符串。                     |
+
+
+
+## 本地开发
+
+1. **克隆仓库**
+
+   ```bash
+   git clone http://git.chengyieco.com/chengyi-frondend-monitor-sdk.git
+   cd chengyi-frondend-monitor-sdk
+   ```
+
+2. **安装依赖**
+
+   ```bash
+   npm install
+   ```
+
+3. **运行开发服务器**
+
+   ```bash
+   npm run dev
+   ```
+
+4. **构建生产版本**
+
+   ```bash
+   npm run build
+   ```
+
+5. **运行演示 Demo**
+   启动本地服务器以测试 SDK 功能。
+   ```bash
+   npm run demo
+   ```
+   然后在浏览器中打开 `http://localhost:3000`（或控制台显示的端口）查看演示。
+
+## 许可证
+
+MIT

package/dist/errorHandler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 开启 JavaScript 错误监控
+ * 监听并上报全局的 JavaScript 运行时错误和未处理的 Promise 异常
+ *
+ * @param {string} reportUrl - 错误上报的服务端接口地址
+ * @param {string} projectName - 项目名称，用于在后台区分错误来源
+ * @param {string} environment - 运行环境（如 'production', 'development'）
+ */
+export declare const monitorJavaScriptErrors: (reportUrl: string, projectName: string, environment: string) => void;

package/dist/index.cjs.js

@@ -0,0 +1,471 @@
+'use strict';
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+var extendStatics = function(d, b) {
+    extendStatics = Object.setPrototypeOf ||
+        ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+        function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+    return extendStatics(d, b);
+};
+
+function __extends(d, b) {
+    if (typeof b !== "function" && b !== null)
+        throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+    extendStatics(d, b);
+    function __() { this.constructor = d; }
+    d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+}
+
+var __assign = function() {
+    __assign = Object.assign || function __assign(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+
+function __awaiter(thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+}
+
+function __generator(thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+}
+
+function __spreadArray(to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+/**
+ * 获取浏览器信息
+ * 解析 userAgent 获取浏览器名称和版本
+ *
+ * @returns {{ name: string, version: string }} 包含浏览器名称和版本的对象
+ */
+var getBrowserInfo = function () {
+    var ua = navigator.userAgent;
+    var tem;
+    var match = ua.match(/(opera|chrome|safari|firefox|msie|trident(?=\/))\/?\s*(\d+)/i) || [];
+    if (/trident/i.test(match[1])) {
+        tem = /\brv[ :]+(\d+)/g.exec(ua) || [];
+        return { name: 'IE', version: tem[1] || '' };
+    }
+    if (match[1] === 'Chrome') {
+        tem = ua.match(/\b(OPR|Edge)\/(\d+)/);
+        if (tem != null) {
+            return { name: tem[1].replace('OPR', 'Opera'), version: tem[2] };
+        }
+    }
+    match[2] = match[2] || '';
+    var name = match[1];
+    var version = match[2];
+    return { name: name, version: version };
+};
+/**
+ * 格式化错误消息
+ *
+ * @param {any} err - 错误对象
+ * @returns {string} 格式化后的错误字符串
+ */
+var formatErrorMessage = function (err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    try {
+        return JSON.stringify(err);
+    }
+    catch (_a) {
+        return String(err);
+    }
+};
+var getUserInfo = function () {
+    var info = JSON.parse(localStorage.getItem('user-info') || '{}') || {
+        id: null
+    };
+    return info;
+};
+
+/**
+ * 发送错误数据到指定URL
+ *
+ * @param {Record<string, any>} errorData - 要发送的错误数据对象
+ * @param {string} url - 目标API端点URL
+ *
+ * @description
+ * 优先使用navigator.sendBeacon方法发送数据，如果浏览器不支持则回退到fetch API。
+ * sendBeacon方法在页面卸载时也能可靠地发送数据。
+ */
+var sendErrorData = function (errorData, url) {
+    // 获取浏览器信息并合并到错误数据中
+    var browserInfo = getBrowserInfo();
+    var userInfo = getUserInfo();
+    var dataToSend = __assign(__assign(__assign({}, errorData), browserInfo), { resource: window.location.href });
+    if (userInfo.id) {
+        dataToSend.userId = userInfo.id;
+    }
+    if (navigator.sendBeacon) {
+        var blob = new Blob([JSON.stringify(dataToSend)], { type: 'application/json' });
+        navigator.sendBeacon(url, blob);
+    }
+    else {
+        fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(dataToSend),
+            keepalive: true, // 即使页面关闭也能发送请求，作用类似 sendBeacon
+        }).catch(function (error) { return console.error('Error reporting failed:', error); });
+    }
+};
+
+/**
+ * 开启 JavaScript 错误监控
+ * 监听并上报全局的 JavaScript 运行时错误和未处理的 Promise 异常
+ *
+ * @param {string} reportUrl - 错误上报的服务端接口地址
+ * @param {string} projectName - 项目名称，用于在后台区分错误来源
+ * @param {string} environment - 运行环境（如 'production', 'development'）
+ */
+var monitorJavaScriptErrors = function (reportUrl, projectName, environment) {
+    // 保存原有的 onerror 处理函数，防止覆盖
+    var originalOnError = window.onerror;
+    /**
+     *  捕获未处理的 JavaScript 错误
+     * @param message (string): 错误的描述信息（例如 "Uncaught ReferenceError: x is not defined"）。
+     * @param source  (string): 发生错误的脚本文件的 URL。
+     * @param lineno  (number): 错误发生的行号。
+     * @param colno  (number): 错误发生的列号。
+     * @param error  (Error Object): 包含详细堆栈信息（Stack Trace）的 Error 对象。这是最有用的部分，因为它能告诉你错误调用的上下文。
+     */
+    window.onerror = function (message, source, lineno, colno, error) {
+        var errorInfo = {
+            message: message,
+            source: source,
+            lineno: lineno,
+            colno: colno,
+            stack: error ? error.stack : null,
+            projectName: projectName,
+            environment: environment,
+            errorType: 'JavaScript Error',
+            timestamp: new Date().toISOString(),
+            userAgent: navigator.userAgent,
+        };
+        // 上报错误数据
+        sendErrorData(errorInfo, reportUrl);
+        // 如果原来有 onerror 处理函数，继续执行它
+        // 这样做是为了不破坏宿主环境（例如用户自己写的或其他 SDK）已有的错误处理逻辑
+        if (originalOnError) {
+            return originalOnError(message, source, lineno, colno, error);
+        }
+    };
+    // 保存原有的处理函数
+    var originalOnUnhandledRejection = window.onunhandledrejection;
+    // 捕获未处理的 Promise 错误
+    window.onunhandledrejection = function (event) {
+        var reason = event.reason;
+        var errorInfo = {
+            message: reason ? (reason.message || String(reason)) : 'Unknown Promise Error',
+            stack: reason && reason.stack ? reason.stack : null,
+            projectName: projectName,
+            environment: environment,
+            errorType: 'Unhandled Promise Rejection',
+            timestamp: new Date().toISOString(),
+            userAgent: navigator.userAgent,
+        };
+        // 上报错误数据
+        sendErrorData(errorInfo, reportUrl);
+        // 如果原来有处理函数，继续执行它
+        // 保持对原有 Promise 错误处理逻辑的兼容性
+        if (originalOnUnhandledRejection) {
+            return originalOnUnhandledRejection.call(window, event);
+        }
+    };
+};
+
+/**
+ * 开启网络错误监控
+ * 劫持并监听 XMLHttpRequest 和 fetch 请求，捕获网络异常
+ *
+ * @param {string} reportUrl - 错误上报地址
+ * @param {string} projectName - 项目名称
+ * @param {string} environment - 运行环境
+ */
+var monitorNetworkErrors = function (reportUrl, projectName, environment) {
+    // 劫持 XMLHttpRequest​
+    // 保存原生的 open 方法，以便后续调用
+    var originalXhrOpen = XMLHttpRequest.prototype.open;
+    XMLHttpRequest.prototype.open = function (method, url) {
+        var args = [];
+        for (var _i = 2; _i < arguments.length; _i++) {
+            args[_i - 2] = arguments[_i];
+        }
+        var _urlStr = typeof url === 'string' ? url : String(url);
+        if (_urlStr.includes(reportUrl)) {
+            return originalXhrOpen.apply(this, __spreadArray([method, url], args, true));
+        }
+        // 监听 error 事件，当请求失败时触发
+        this.addEventListener('error', function () {
+            var errorInfo = {
+                message: "Network Error: ".concat(method, " ").concat(url),
+                projectName: projectName,
+                environment: environment,
+                errorType: 'Network Error',
+                timestamp: new Date().toISOString(),
+                userAgent: navigator.userAgent,
+            };
+            sendErrorData(errorInfo, reportUrl);
+        });
+        // 调用原生的 open 方法，保证正常请求流程
+        return originalXhrOpen.apply(this, __spreadArray([method, url], args, true));
+    };
+    // 劫持 fetch​
+    // 保存原生的 fetch 方法
+    var originalFetch = window.fetch;
+    window.fetch = function (input, init) { return __awaiter(void 0, void 0, void 0, function () {
+        var urlStr, response, errorInfo, error_1, errorInfo;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    urlStr = (input instanceof Request) ? input.url : String(input);
+                    if (urlStr.includes(reportUrl)) {
+                        return [2 /*return*/, originalFetch(input, init)];
+                    }
+                    _a.label = 1;
+                case 1:
+                    _a.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, originalFetch(input, init)];
+                case 2:
+                    response = _a.sent();
+                    // 检查响应状态，如果不是 2xx 则视为错误
+                    if (!response.ok) {
+                        errorInfo = {
+                            message: "Network Error: ".concat(response.status, " ").concat(response.statusText),
+                            url: input instanceof Request ? input.url : input,
+                            projectName: projectName,
+                            environment: environment,
+                            errorType: 'Fetch Error',
+                            timestamp: new Date().toISOString(),
+                            userAgent: navigator.userAgent,
+                        };
+                        sendErrorData(errorInfo, reportUrl);
+                    }
+                    return [2 /*return*/, response];
+                case 3:
+                    error_1 = _a.sent();
+                    errorInfo = {
+                        message: "Fetch failed: ".concat((input instanceof Request ? input.url : input)),
+                        projectName: projectName,
+                        environment: environment,
+                        errorType: 'Fetch Error',
+                        timestamp: new Date().toISOString(),
+                        userAgent: navigator.userAgent,
+                    };
+                    sendErrorData(errorInfo, reportUrl);
+                    throw error_1;
+                case 4: return [2 /*return*/];
+            }
+        });
+    }); };
+};
+
+/**
+ * 开启资源加载错误监控
+ * 监听图片、脚本等资源加载失败的错误
+ *
+ * @param {string} reportUrl - 错误上报地址
+ * @param {string} projectName - 项目名称
+ * @param {string} environment - 运行环境
+ */
+var monitorResourceErrors = function (reportUrl, projectName, environment) {
+    /**
+      * 监听全局 error 事件
+      * 注意：资源加载错误不会冒泡，所以必须在捕获阶段处理 (useCapture = true)
+    */
+    window.addEventListener('error', function (event) {
+        var target = event.target;
+        // 过滤出 IMG 和 SCRIPT 标签的错误
+        if (target && (target.tagName === 'IMG' || target.tagName === 'SCRIPT')) {
+            var errorInfo = {
+                message: "Resource Load Error: ".concat(target.tagName, " ").concat(target.getAttribute('src') || target.getAttribute('href')),
+                projectName: projectName,
+                environment: environment,
+                errorType: 'Resource Load Error',
+                timestamp: new Date().toISOString(),
+                userAgent: navigator.userAgent,
+            };
+            sendErrorData(errorInfo, reportUrl);
+        }
+    }, true); // useCapture 为 true 确保资源错误被捕获
+};
+
+var __monitorInitialized = false;
+/**
+ * 初始化错误监控 SDK
+ * 该函数是 SDK 的入口，负责启动各类错误监控模块
+ *
+ * @param {ErrorMonitorConfig} config - 监控配置对象
+ */
+var initErrorMonitor = function (config) {
+    var reportUrl = config.reportUrl, projectName = config.projectName, environment = config.environment;
+    // 初始化各类错误监控
+    monitorJavaScriptErrors(reportUrl, projectName, environment);
+    monitorNetworkErrors(reportUrl, projectName, environment);
+    monitorResourceErrors(reportUrl, projectName, environment);
+};
+var VueErrorMonitorPlugin = {
+    /**
+     * Vue 插件安装函数
+     *
+     * @param {any} app - Vue 应用实例
+     * @param {object} options - 插件配置项
+     * @param {string} options.reportUrl - 上报错误服务端地址
+     * @param {string} options.projectName - 项目名称
+     * @param {string} options.environment - 当前环境
+     */
+    install: function (app, options) {
+        if (!options || !options.reportUrl)
+            return;
+        if (!__monitorInitialized) {
+            initErrorMonitor(options);
+            __monitorInitialized = true;
+        }
+        var cfg = app.config;
+        var original = cfg.errorHandler;
+        /**
+         * 错误处理函数
+         *
+         * @param {unknown} err - 错误对象
+         * @param {unknown} [instance] - Vue 实例
+         * @param {unknown} [info] - 错误信息
+         */
+        cfg.errorHandler = function (err, instance, info) {
+            var e = err;
+            sendErrorData({
+                message: formatErrorMessage(err),
+                stack: e && e.stack ? e.stack : null,
+                projectName: options.projectName,
+                environment: options.environment,
+                errorType: 'Vue Error',
+                timestamp: new Date().toISOString(),
+                userAgent: navigator.userAgent,
+                info: info,
+            }, options.reportUrl);
+            if (typeof original === 'function') {
+                try {
+                    original(err, instance, info);
+                }
+                catch (_a) { }
+            }
+        };
+    }
+};
+/**
+ * 创建 React 错误边界组件
+ *
+ * @param {object} React - React 库对象
+ * @param {object} config - 错误监控配置
+ * @param {string} config.reportUrl - 上报错误服务端地址
+ * @param {string} config.projectName - 项目名称
+ * @param {string} config.environment - 当前环境
+ * @returns {React.Component} - 创建的错误边界组件
+ */
+var createReactErrorBoundary = function (React, config) {
+    // 确保在创建边界组件时启动全局监控（JS/网络/资源）
+    if (config && config.reportUrl && !__monitorInitialized) {
+        initErrorMonitor(config);
+        __monitorInitialized = true;
+    }
+    return /** @class */ (function (_super) {
+        __extends(ErrorMonitorBoundary, _super);
+        function ErrorMonitorBoundary(props) {
+            var _this = _super.call(this, props) || this;
+            _this.state = { hasError: false };
+            return _this;
+        }
+        ErrorMonitorBoundary.getDerivedStateFromError = function () { return { hasError: true }; };
+        ErrorMonitorBoundary.prototype.componentDidCatch = function (error, info) {
+            sendErrorData({
+                message: formatErrorMessage(error),
+                stack: (error === null || error === void 0 ? void 0 : error.stack) || null,
+                projectName: config.projectName,
+                environment: config.environment,
+                errorType: 'React Error',
+                timestamp: new Date().toISOString(),
+                userAgent: navigator.userAgent,
+                componentStack: (info === null || info === void 0 ? void 0 : info.componentStack) || null,
+            }, config.reportUrl);
+        };
+        ErrorMonitorBoundary.prototype.render = function () {
+            if (this.state.hasError)
+                return this.props.fallback || null;
+            return this.props.children;
+        };
+        return ErrorMonitorBoundary;
+    }(React.Component));
+};
+
+exports.VueErrorMonitorPlugin = VueErrorMonitorPlugin;
+exports.createReactErrorBoundary = createReactErrorBoundary;
+exports.initErrorMonitor = initErrorMonitor;
+//# sourceMappingURL=index.cjs.js.map