用途
@vercel/error 用于设计、实现、迁移、审计或审查结构化 TypeScript 错误。其核心理念是：使用结构化字段标识“什么失败了”“为什么失败”以及“下一步该做什么”。软件应基于稳定字段进行分支判断，而人和智能体应阅读文字描述。字段需保留到输出渲染阶段，且不应解析终端格式化内容。
主要能力
该包提供以下公开 API，按需求选择：
- VercelErrorOptions：用于决定错误码、详情、公开文本和上报方式，属于契约设计。
- VercelError 及核心守卫与提取器：用于构造单个错误、定义子类、保留 cause，或检查捕获的值，属于核心错误。
- createErrors：用于创建带共享字段、文档、上报或自定义类的类型化错误族，属于 createErrors 工厂。
- errorResponse、fromHttpResponse、parseErrorResponseData、fromErrorResponseData：用于生成或消费 HTTP 错误响应，属于 HTTP 错误。
- formatError、frame、hint、fix、link：用于将错误格式化为终端输出，属于终端输出。
对于 VercelError，使用其 toString() 方法，它已使用该包的格式化器。对于应保持其他类型的错误或 CLI 输出，使用 frame()。
使用方式
工作流程如下：
-
检查目标项目：在选择 API 前，阅读目标项目的 package.json、锁文件、现有错误、输出路径、日志和测试。以已安装的 @vercel/error 版本的公开导出作为契约，不要深度导入未导出的源码路径。若包不存在，从工作区约束或当前发布版本确定目标版本，再检查其已发布导出和 engines。仅在请求实现工作时将其添加为生产依赖。比较 Node 目标版本与所选版本的 engines，若存在不兼容应报告，而非静默更改运行时。记录项目现有的代码和作用域名称及依赖它们的调用方。在建议和审查工作中，保持依赖不变。继续前，记录所选版本和运行时兼容性，验证公开导入，并确定错误在何处创建、处理、发送、记录或展示。
-
判断是否需要结构化错误：对于无需调用方分类、传输、上报或展示恢复指引的简单本地失败，保留原生 Error。当至少需要以下之一时使用 @vercel/error：稳定的 code 或 scope；结构化的 reason、hint、fix 或 documentation；HTTP 传输与重建；遥测或调试上下文；一致的终端呈现；跨打包或 realm 边界的可靠识别。仅当能指明需要它的调用方、传输、日志器或 UI 时才使用结构化错误，“更一致”不足以作为理由。
-
选择公开 API：根据需求对照上表选择。阅读与工作匹配的每个参考。当所有必需操作都映射到所选包版本中已验证的公开导入时继续。
-
选择字段和恢复指引：对作用域内每个字段应用契约设计，包括其反驳规则。实现前，验证每个填充字段都有已知用途，且每个客户端可见字段都是安全的。设置时，scope 和 code 必须非空，保留其原始文本。省略空的可选公开字段，保留其他文本。
-
实现或审查：对于审查工作，报告正确性、披露和恢复方面的缺口；仅在要求时编辑。对于实现，仅更改需要结构化字段的错误路径。保留周围行为、代码约定和第三方错误类型。将项目范围的 code 或 scope 重命名视为单独的迁移。代码示例必须在所示上下文中通过类型检查，或标注为部分替换。
-
测试公开行为：测试消费错误的行为，而非私有格式化辅助函数：通过工厂创建、抛出和上报（当这些路径重要时）；用于程序化处理的稳定 code 和保留的 cause；JSON 和 ANSI 中相同的公开字段，以及 Content-Type、条件 Vary 和 HTTP 状态；在重建前拒绝无效的未知响应数据；带和不带可选部分的终端输出；目标项目使用的实际公开包入口点。先运行目标项目最接近的测试和类型检查，再运行其必需检查。
适用场景
适用于需要稳定错误码或作用域、结构化原因/提示/修复/文档、HTTP 传输与重建、遥测或调试上下文、一致终端呈现，以及跨打包或 realm 边界可靠识别的项目。该包为同构设计，可用于浏览器、worker 和边缘运行时；其 engines 字段表示 Node 支持矩阵，而非运行时白名单。
限制
对于无需调用方分类、传输、上报或展示恢复指引的简单本地失败，不应使用结构化错误，而应保留原生 Error。仅当能指明需要它的调用方、传输、日志器或 UI 时才使用。不要深度导入未导出的源码路径。在建议和审查工作中保持依赖不变。若 Node 目标版本与所选版本的 engines 不兼容，应报告而非静默更改运行时。