uni-app 开源仓库 UTS 内置对象 Error 完全指南：错误创建、属性详解与跨端异常处理

uni-app 开源仓库 UTS 内置对象 Error 完全指南错误创建、属性详解与跨端异常处理【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读本文以 uni-app 开源仓库 docs/uts/buildin-object-api/error.md 为核心系统讲解 UTSuni type script语言中的内置对象Error包括运行时错误的产生机制、message与cause两个实例属性的语义、三种创建Error的写法以及结合throw/try...catch的完整异常处理流程。同时结合仓库源码与测试用例深入剖析Error在 AndroidKotlin平台的编译产物UTSError、与框架级UniError的区别以及跨端错误处理的最佳实践。读完本文你将能够在 UTS 插件与 uvue 页面中正确创建、包装、捕获与传播错误。Error 是什么在 UTS 中当运行时错误产生时Error对象会被抛出throw。同时Error也可作为开发者自定义异常的基础对象通过继承或直接实例化来表达业务层面的错误语义。UTS 是一门强类型、可编译到多平台原生语言的现代编程语言详见 docs/uts/README.mdWeb 平台 / 小程序编译为 JavaScriptAndroid 平台编译为 Kotlinuts 插件内iOS 平台编译为 Swiftuts 插件内鸿蒙 OS 平台编译为 ArkTSuts 插件内。由于Error属于 UTS 的内置对象buildin object它在不同平台的编译产物并不相同。这一点在仓库文档 docs/plugin/uts-plugin-hybrid.md 的「uts 和 kotlin 对象映射表」中有明确记录UTS 内置对象编译成的原生类名Arrayio.dcloud.uts.UTSArrayNumberkotlin.NumberStringkotlin.StringDateio.dcloud.uts.DatePromiseio.dcloud.uts.UTSPromiseErrorio.dcloud.uts.UTSError也就是说在 Android 平台Kotlin上你写的new Error(...)最终会实例化为io.dcloud.uts.UTSError在 iOSSwift、WebJS等其他平台则对应各自的错误类型实现。理解这一点有助于你在 uts 插件与原生代码Kotlin/Swift交互时正确识别和转换错误对象。实例属性Error实例主要暴露两个属性message与cause。message错误消息message表示错误消息文本。对于开发者手动创建的Error对象message的值就是构造函数第一个参数传入的字符串对于运行时如引擎或系统抛出的错误message则是运行时提供的描述信息。仓库中的自动化测试用例 examples/hello-uts/uni_modules/uts-tests/utssdk/Error.uts 直接验证了这一行为test(message, () { try { throw new Error(Whoops!) } catch (e) { expect((e as Error).message).toEqual(Whoops!); } })该用例展示了两个要点通过new Error(Whoops!)抛出的错误其message属性严格等于构造参数Whoops!在catch分支中捕获到的异常对象e需要显式断言为Error类型(e as Error)后才能安全访问message这体现了 UTS 的强类型约束——与 TypeScript 类似捕获的异常需要类型收窄后才能使用其具体成员。cause原始错误原因cause用于保存「导致该错误的具体原始原因」。典型场景是错误包装error wrapping底层调用抛出某个原始错误上层捕获后将其包装进一个更具体、对调用方更有用的错误通过cause字段仍可回溯访问到原始错误避免丢失根因信息。这是 JS/TS 生态中常见的错误链路追溯模式。在 UTS 中该语义与 TypeScript 保持一致new Error(message, { cause: 原始错误 })。创建 ErrorUTS 支持以下三种创建方式与 docs/uts/buildin-object-api/error.md 保持一致// 直接创建无消息 let error new Error(); // 指定 message let err new Error(Whoops!); // 同时指定 message 和 cause错误包装 let otherError new Error(Connecting to database failed., { cause: err });第一种方式创建无消息的空错误适用于仅表达「发生了一个错误」而不需要细节的场合第二种是最常用的写法第三种用于错误包装将底层异常作为cause挂载到新错误上形成可追溯的错误链。抛异常与捕获异常仅创建Error对象不会产生任何效果必须通过throw抛出、由try...catch捕获异常处理链路才完整。相关语法在仓库文档 docs/uts/exception.md 中有系统说明。throw抛出异常使用throw表达式抛出一个异常通常搭配new Error(...)throw new Error(Hi There!);在仓库的 uvue 示例页面 examples/hello-uvue/pages/error/throw-error/throw-error-composition.uvue 中展示了多种触发错误的方式页面生命周期回调中直接抛出、按钮事件处理器中抛出、以及setTimeout定时回调中抛出onReady(() { throw new Error(error in error composition page onReady) }) const triggerError () { throw new Error(trigger error in throw error composition page) } const triggerTimeoutError () { setTimeout(() { throw new Error(setTimeout trigger error in throw error composition page) }, 10) }该示例页面同样提供了选项式 API 的对照实现见 throw-error-options.uvue说明无论采用组合式还是选项式写法throw new Error(...)的用法完全一致。try...catch...finally捕获与兜底使用try...catch表达式捕获异常finally块可选try { // 一些代码 } catch (e: Error) { // 处理程序 } finally { // 可选的 finally 块 }三段式语义如下try块存放可能抛出异常的代码catch (e: Error)捕获并处理异常可对异常对象做类型标注后进行针对性处理finally块无论是否发生异常都会执行适合释放资源、恢复状态等收尾逻辑。iOS 平台注意事项一个重要的跨端差异在 iOS 平台由于 Swift 的语法特性无法直接使用try...catch。iOS 平台上使用try的特殊语法详见 docs/plugin/uts-for-ios.md 中关于 try 的章节。如果插件需要同时兼容 iOS 与其他平台建议将try...catch代码置于条件编译中或采用 Swift 侧的错误处理约定。平台编译差异UTSError 与 UniErrorAndroid 平台的 UTSError前文已述Error在 AndroidKotlin平台编译为io.dcloud.uts.UTSError记录于 docs/plugin/uts-plugin-hybrid.md 与 docs/uts/buildin-object-api/error.md 的 Bug Tips 一节。这意味着在编写 uts 插件时若需要在 Kotlin 原生代码与 UTS 环境之间互传错误对象应留意该映射关系原生侧捕获到UTSError与 UTS 侧的Error是同一个对象反之亦然。在原生与 UTS 环境互传数据时文档建议尽量转换为标准内置对象后再传递以规避平台差异见 docs/plugin/uts-plugin-hybrid.md。框架级错误对象 UniError除语言层面的Error外uni-app 框架在 API 层还提供了UniError对象用于描述 API 调用失败的具体信息如errSubject、errCode、errMsg其结构规范见 docs/err-spec.md。两者定位不同ErrorUTS 语言内置对象面向运行时错误与自定义异常的通用错误UniErroruni-app 框架 API 层的统一错误返回体常用于fail回调参数。仓库测试 examples/hello-uts/uni_modules/uts-tests/utssdk/Error.uts 同时覆盖了两者test(UniError, () { expect(new UniError().message).toEqual() expect(new UniError(Whoops!).message).toEqual(Whoops!) })从该用例可以看出UniError同样支持无参构造与携带消息构造且其message语义与Error一致。在 docs/api/get-file-system-manager.md 中还能看到实战组合用法——用new UniError(res.errSubject, res.errCode, res.errMsg)将 API 回调中的错误信息重构为完整的UniError对象便于统一处理和上报。错误包装与 cause 链的实战模式结合cause属性与try...catch可以构建标准的错误包装链路。设底层函数connectDatabase()可能抛出连接错误上层服务捕获后包装为带有业务语义的错误同时保留根因function connectDatabase() { // 底层可能抛错 throw new Error(connection refused); } function queryUser() { try { connectDatabase(); } catch (e) { // 包装向上层抛出更具体的错误并通过 cause 保留原始错误 throw new Error(queryUser failed: database unavailable., { cause: e }); } } try { queryUser(); } catch (e) { const err e as Error; console.log(err.message); // 输出包装后的业务错误消息 console.log(err.cause); // 可回溯到原始连接错误 }这种模式的价值在于上层调用方只需处理统一包装后的错误类型与消息而排查问题时仍能通过cause一路回溯到最底层的真实根因避免错误信息在多层传递中被稀释。使用注意与最佳实践结合原文档的 Bug Tips 与仓库内相关文档归纳以下实践要点牢记平台映射Error在 Android 平台编译为io.dcloud.uts.UTSError编写 uts 插件与 Kotlin 原生代码交互时需注意类名对应关系docs/plugin/uts-plugin-hybrid.md。iOS 的 try 限制iOSSwift平台无法直接使用try...catch需要参考 docs/plugin/uts-for-ios.md 的 try 语法必要时使用条件编译隔离平台差异。捕获后做类型断言catch分支中访问错误成员前先用(e as Error)进行类型收窄这是 UTS 强类型约束下的标准写法参见 docs/uts/uts_diff_ts.md 中 uts 与 ts 差异的说明。区分 Error 与 UniError语言内部逻辑、自定义异常用Error与 uni-app API 交互、处理fail回调错误信息时用UniError后者携带errSubject/errCode/errMsg等结构化字段docs/err-spec.md。善用 cause 保持错误链包装错误时务必通过{ cause: 原始错误 }挂载根因保证多层调用后仍可完整回溯。消息要可读、可定位为new Error(...)提供准确、包含上下文信息的 message便于日志排查页面与插件中抛出的错误消息应能定位到具体页面、生命周期或操作参考 throw-error-composition.uvue 的命名风格。深入阅读UTS 内置对象 Error 官方文档本文的直接依据UTS 异常处理throw / try...catch异常抛出的完整语法UTS 语言介绍与编译目标了解各平台编译产物uts 与 ts 的差异强类型约束与跨端限制UTS 与 Kotlin 对象映射表Error → UTSError 的类名对应错误规范 err-specUniError 结构定义Error 自动化测试用例message 与 UniError 的行为验证uvue 页面抛出错误示例页面场景下的 throw 实践。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考