@composy/error-vue

LDesign Vue 3 错误处理适配包，提供 ErrorBoundary、错误提示组件、composable、directive 和插件安装能力。核心错误模型、捕获、去重、限流、上报和诊断全部复用 @composy/error-core。

配置与构建

• .ldesign/eslint.config.js、.ldesign/tsconfig.json 和 .ldesign/tsconfig.typecheck.json 是本包 ESLint / TypeScript 的权威配置。
• 构建使用本目录 .ldesign/builder.config.ts 的 @composy/builder / rolldown 配置；Playground 的 TypeScript 配置为 .ldesign/tsconfig.playground.json。
• tsconfig.json、tsconfig.typecheck.json 和 playground/tsconfig.json 保留为兼容 shim。
• pnpm run type-check 检查 Vue 源码和 Playground，pnpm run build 生成并校验发布产物。

安装

pnpm add @composy/error-vue @composy/error-core vue

快速使用

import { createErrorManager, createErrorVuePlugin } from '@composy/error-vue'
import { createApp } from 'vue'
import App from './App.vue'

const errorManager = createErrorManager({
  reporter: {
    endpoint: '/api/errors',
  },
})

createApp(App)
  .use(
    createErrorVuePlugin({
      manager: errorManager,
      enableToast: true,
      registerDirective: true,
      showVueErrors: true,
    }),
  )
  .mount('#app')

当 createErrorVuePlugin() 未接收外部 manager 时，它拥有该 manager 的生命周期：最后一个安装该插件的 Vue app 卸载后会自动销毁 manager，释放全局监听与上报器资源。传入 manager 时生命周期仍由调用方控制。

插件安装会保存并在卸载时恢复 app 原有的 config.errorHandler、$errorManager、$errorHandler 和 $errorToast。同一个 app 重复安装同一个 manager 是幂等操作；不同 manager 不会覆盖已经存在的安装。Engine Vue bridge 会为延迟的 app:created 回调绑定 generation，卸载或新一轮安装后到达的旧回调不会重新注入 Vue app。

Tracker 默认只采集事件名、标签名和脱敏后的 pathname，不读取 DOM 文本、id、className 或 URL 查询参数；如需更丰富的上下文，应通过显式的 safeData 配置提供。

ErrorBoundary

<script setup lang="ts">
import type { ErrorInfo } from '@composy/error-vue'
import { ErrorBoundary } from '@composy/error-vue'

function handleError(error: ErrorInfo): void {
  console.info('[vue boundary]', error.message)
}
</script>

<template>
  <ErrorBoundary :show-stack="import.meta.env.DEV" @error="handleError">
    <RiskyPanel />

    <template #fallback="{ error, retry }">
      <section class="fallback">
        <strong>{{ error.message }}</strong>
        <button type="button" @click="retry">重试</button>
      </section>
    </template>
  </ErrorBoundary>
</template>

Composable

import { useErrorHandler } from '@composy/error-vue'

const { errors, hasError, captureError, addBreadcrumb, clearErrors, flush } = useErrorHandler()

// addBreadcrumb(type, category, message, data?)
addBreadcrumb('click', 'profile', 'save profile')

captureError(new Error('保存失败'))
console.info(hasError.value, errors.value.length)

await flush()
clearErrors()

useErrorHandler() 在没有注入 manager/handler 时会创建局部 catcher/reporter，并在组件卸载时释放它们。异步回调不会在卸载后再次写入响应式状态。useAsyncError() 的 cancelOnUnmount 选项（默认关闭）会在卸载时取消未完成的超时与重试等待；底层 Promise 本身仍由调用方负责取消。

Directive

<template>
  <section v-error-boundary="{ mode: 'overlay', showToast: true }">
    <RiskyPanel />
  </section>
</template>

主要导出

• ErrorBoundary、ErrorFallback、ErrorInline、ErrorOverlay、ErrorToast
• useErrorHandler()、useAsyncError()、useErrorScope()、useGlobalErrorToast()
• vErrorBoundary、vResourceErrorBoundary
• createErrorVuePlugin()、installErrorVue()、createErrorEngineVuePlugin()
• createErrorManager()、ErrorManager、ErrorReporter、ErrorCatcher
• withScope()、withScopeAsync()、ErrorLevel、ErrorSource

构建产物

本包显式使用 @composy/builder 的内置 rolldown，构建后保持四类产物：

• es/：ESM + 类型声明，作为主 module / types 入口。
• esm/：保留 Less 源样式，便于业务二次构建。
• lib/：CommonJS 产物。
• dist/：UMD、压缩 UMD、index.css 和 index.min.css。

样式可通过 @composy/error-vue/index.css 使用完整压缩前 CSS，或通过 @composy/error-vue/style.css / @composy/error-vue/style.less 进入构建链。每次构建都会归一化产物，并校验入口、exports、sourcemap、压缩 UMD、lib/package.json 与样式文件。

本地验证

pnpm --dir packages/error/packages/vue run type-check
pnpm --dir packages/error/packages/vue run test:run
pnpm --dir packages/error/packages/vue run build
pnpm --dir packages/error run outputs:check

相关链接

• 家族总览
• @composy/error-core —— 框架无关核心实现

License

MIT © LDesign Team