Vitest项目中自定义错误对象的JSON格式化问题解析

在Vitest测试框架中，当开发者使用自定义错误对象时，如果错误对象实现了toJSON方法，测试控制台的错误输出可能会以JSON对象的形式呈现，而不是传统的错误堆栈格式。这种现象虽然不影响功能，但会降低开发者的调试体验。

问题本质

自定义错误对象通过toJSON方法序列化后，Vitest会优先使用该方法返回的对象进行错误展示。如果返回的JSON对象中缺少标准错误属性（特别是message属性），Vitest会默认展示整个JSON对象结构，导致以下问题：

1. 错误信息呈现为复杂的JSON结构，不易阅读
2. 堆栈信息被多次重复展示（原始格式和解析后格式）
3. 关键错误信息可能被埋没在大量元数据中

解决方案

要使自定义错误在Vitest控制台中正确格式化，需要确保：

1. 在toJSON方法返回的对象中包含message属性
2. 保持与原生Error对象相似的属性结构

示例实现：

class MyError extends Error {
  tag = 'MY_ERROR'
  
  toJSON() {
    return {
      message: this.message,  // 必须包含
      name: this.name,
      stack: this.stack,
      tag: this.tag
    }
  }
}

最佳实践建议

1. 保持兼容性：自定义错误应继承自原生Error类，保留标准错误接口
2. 结构化序列化：在toJSON中返回结构化数据时，包含至少message和stack属性
3. 避免信息冗余：不要在序列化对象中重复存储已存在于标准错误属性中的数据
4. 考虑测试环境：专门为测试环境实现toString方法，提供更友好的错误展示

技术原理

Vitest的错误展示机制会检查错误对象的以下属性，按优先级处理：

1. 首先检查message属性作为主要错误信息
2. 如果没有message，则尝试使用toString()结果
3. 最后才会回退到展示整个对象结构

当实现toJSON时，返回的对象若缺少这些标准属性，就会触发第三种展示方式，这也是导致JSON对象直接输出的根本原因。

总结

在Vitest中使用自定义错误时，开发者需要注意保持与原生错误对象的兼容性。通过合理实现toJSON方法并确保包含必要的标准错误属性，可以既满足序列化需求，又保持测试输出良好的可读性。这体现了在定制化开发中保持API兼容性的重要性，也是框架设计中的常见考量点。