✅ README.md

🛡️ tenson-wd-error-shield

轻量级前端异常守护者 —— 实时捕获未处理错误、Promise 拒绝、Vue/uni-app 异常，防止静默失败，助力稳定开发！

tenson-wd-error-shield 是一个通用型前端错误监控工具，专为 Vue2、Vue3、TSX、uni-app 等现代前端项目设计。它能自动监听：

• ⚠️ 未被捕获的异常（throw 错误）
• 🔴 未处理的 Promise.reject
• 🤫 被“吞掉”的错误提示（静默失败）
• 🖥️ Vue 组件内部错误（支持 Vue2 & Vue3）
• 📱 uni-app 多端运行时错误

开箱即用，无需复杂配置，帮助你在开发和生产环境中快速发现并定位问题。

📦 安装

使用 npm 或 yarn 安装：

npm install tenson-wd-error-shield
或
yarn add tenson-wd-error-shield

> 支持 ES6 Module 和 CommonJS 引入方式。

***

## 🚀 快速使用

在你的项目入口文件（如 `main.js`、`main.ts` 或 `app.js`）中引入并启用：

// main.js
import { useErrorShield } from 'tenson-wd-error-shield';

useErrorShield();

✅ 完成！现在所有未处理的异常都会被实时捕获，并在控制台高亮输出。

***

## 🎨 自定义反馈行为

你可以通过传入选项来自定义错误处理逻辑，例如上报到服务器或关闭提示：

useErrorShield({
  // 自定义错误处理器
  onError: (error, context) => {
    console.group(`🚨 [ErrorShield] 捕获异常`);
    console.error('Error:', error);
    console.info('Context:', context);
    console.groupEnd();

    // 👇 可以上报到你的日志服务
    fetch('/api/log-error', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        message: error.message,
        stack: error.stack,
        type: context.type,
        url: location.href,
        timestamp: Date.now()
      })
    }).catch(() => {
      // 静默失败处理
    });
  },

  // 是否开启 Promise 异常捕获（默认 true）
  capturePromises: true,

  // 是否静默模式（不打印日志，用于生产环境收集）
  silent: false
});

***

## 🔌 支持的框架

| 框架     | 支持情况 | 说明 |
|----------|----------|------|
| Vue 2    | ✅       | 自动注入 `Vue.config.errorHandler` |
| Vue 3    | ✅       | 支持 `app.config.errorHandler` |
| TSX/JSX  | ✅       | 兼容 JSX 环境中的运行时错误 |
| uni-app  | ✅       | 支持 H5、小程序等多端错误监听 |
| 原生 JS  | ✅       | 全局错误 + unhandledrejection 捕获 |

无需额外配置，只要页面加载了 Vue 或 uni-app，`tenson-wd-error-shield` 会自动识别并集成。

***

## 支持平台

- ✅ H5 / Web
- ✅ Vue 2 / Vue 3
- ✅ uni-app（H5 + 小程序）
- ✅ 微信小程序
- ✅ 支付宝小程序
- ✅ 抖音/头条小程序
- ✅ QQ / 百度小程序

## 小程序使用

1. 将 `dist/error-shield.min.js` 复制到小程序 `utils/` 目录
2. `const ErrorShield = require('./utils/error-shield.min.js')`
3. `ErrorShield.useErrorShield({ onError })`

## 🧪 开发建议

* **开发环境**：建议开启默认提示，便于及时发现问题。
* **生产环境**：可设置 `silent: true` 并结合 `onError` 上报错误日志，避免干扰用户。

useErrorShield({
  silent: process.env.NODE_ENV === 'production',
  onError: (error, context) => {
    if (process.env.NODE_ENV === 'production') {
      reportToAnalytics(error, context); // 上报服务
    } else {
      alert(`[ErrorShield] 发现未处理错误：${error.message}`);
    }
  }
});

***

## 📄 许可证

MIT License © \[Your Name]

开源地址：<https://www.npmjs.com/package/tenson-wd-error-shield>

***

## 💬 反馈与贡献

欢迎提交 Issue 或 Pull Request！

* 发现 Bug？→ [提 Issue](https://www.npmjs.com/package/tenson-wd-error-shield/issues)
* 想要新功能？→ [提 Feature Request](https://www.npmjs.com/package/tenson-wd-error-shield/issues)
* 想要参与开发？👏 欢迎 Fork 并提交 PR！

***

🛡️ 让每一个错误都无处遁形。