跳到主要内容
版本：dev

故障排查

本页介绍使用 Fory JavaScript 时的常见问题。

无法反序列化非跨语言载荷​

Fory JavaScript 只能读取 Fory 跨语言载荷。如果生成方是使用原生模式格式的 Java 或 Go 服务，JavaScript 端无法解码。

解决方法：将生成方切换为 xlang 载荷。Java 和 Go 默认使用 xlang；除非每个通信方使用相同 Schema，否则应使用兼容模式。

maxDepth must be an integer >= 2​

这表示传入了无效的 maxDepth 值。它必须是至少为 2 的正整数。

new Fory({ maxDepth: 100 });

仅当数据确实深度嵌套时才提高此值。

Field "..." is not nullable​

你正在向未声明为可空的字段传入 null。解决方法：在字段 Schema 上添加 .setNullable(true)：

const userType = Type.struct("example.user", {
  name: Type.string(),
  email: Type.string().setNullable(true), // ← this field can be null
});

反序列化后的对象不是同一个实例​

Fory 默认不保留对象标识。指向同一个对象的两个字段会变成两个独立副本。

解决方法：同时启用以下两项：

  1. 在实例上使用 new Fory({ ref: true })
  2. 在具体字段上使用 .setTrackingRef(true)

参见引用。

大整数返回为 bigint​

这是预期行为。Fory 使用 bigint 处理所有 64 位整数字段（Type.int64()、Type.uint64()）。如果需要 number，请使用 Type.int32() 等较小的整数类型，但前提是该值确实可以放入 32 位。

检查生成的序列化器代码​

如果需要调试 Fory 的内部行为，可以通过 hook 检查生成的序列化器代码：

const fory = new Fory({
  hooks: {
    afterCodeGenerated(code) {
      console.log(code);
      return code;
    },
  },
});

@apache-fory/hps 安装失败​

@apache-fory/hps 是可选的 Node.js 加速器。如果安装失败（例如平台不支持原生模块），只需将它从依赖中移除。没有它，Fory 仍能正常工作。

相关主题​