JS对象转JSON字符串:JSON.stringify()用法详解

作者:木棉时间:2026-11-20 15:35:12浏览:303

深入解析JavaScript中JSON.stringify()的完整用法,系统讲解语法三参数、replacer过滤机制、space格式化排版、特殊数据类型序列化边界以及循环引用等常见陷阱与解决方案。

ECMAScript 5.1+ JSON 数据标准 实用技术详解

将 JavaScript 内存中的对象转换为符合 JSON 格式的文本字符串,最直接且标准的方法是调用内置方法 JSON.stringify()。在实际业务中,除了基础的数据序列化外,开发者常常需要过滤敏感字段、对输出结果进行排版美化,以及安全应对 undefined、函数或循环引用带来的丢失与报错问题。本文将全面拆解该方法的三个参数、执行原理、特殊类型边界行为与高频避坑实践。

JS对象转JSON字符串:JSON.stringify()用法详解
图 0:JSON.stringify() 语法签名与三大核心能力概览

一、基础语法与三个核心参数拆解

在 JavaScript 中,JSON.stringify() 负责把一个 JavaScript 对象或值转换为符合 JSON 规范的 UTF-16 文本字符串。完整的函数签名如下:

JSON.stringify(value[, replacer[, space]])

多数情况下开发者只传入第一个参数 value,但其余两个可选参数提供了强大的属性控制与输出排版能力。

参数名 类型要求 默认值 功能与作用说明
value Any 必填 将要序列化的目标 JavaScript 对象、数组或基础原始值。
replacer Function | Array | null null / undefined 属性过滤器。传入数组作为保留属性白名单;传入函数作为逐节点调用的转换器。
space Number | String null / "" 美化输出缩进。传入 1~10 的数字代表空格数;传入字符串则作为每行前缀填充字符。

1. 基础单参数转换:对象与数组

直接传入对象或数组时,方法将按照标准的 JSON 规范生成紧凑的字符串,所有对象的键均会被强制加上双引号包裹:

const user = {
  id: 1001,
  name: "张三",
  roles: ["admin", "editor"],
  isActive: true
};

const jsonStr = JSON.stringify(user);
console.log(jsonStr);
示例输出
"{"id":1001,"name":"张三","roles":["admin","editor"],"isActive":true}"

如果直接序列化基本类型,布尔值、数字和普通字符串会对应输出为字面量字符串;而 null 则输出为 "null"。

2. 缩进控制:利用 space 参数美化排版 (Pretty Print)

默认情况下,JSON.stringify() 生成的字符串不包含换行符与多余空格,适合网络传输以节约带宽。但在调试排查、输出文件配置或本地日志记录时,需要提高人眼可读性。此时可通过第三个参数 space 实现缩进美化。

const config = {
  env: "production",
  port: 8080,
  features: { auth: true, cache: false }
};

// 使用 2 个空格进行多层缩进排版
const formattedJson = JSON.stringify(config, null, 2);
console.log(formattedJson);
示例输出
{
  "env": "production",
  "port": 8080,
  "features": {
    "auth": true,
    "cache": false
  }
}
参数规则说明:space 的上限与填充字符

当 space 为数字时,取值范围为 1 至 10,如果传入大于 10 的数值,引擎将强制截断为 10;如果传入非空字符串(例如 " " 或 "--"),该字符串的前 10 个字符将被作为每一层缩进的填充前缀。

JS对象转JSON字符串:JSON.stringify()用法详解
图 1:JSON.stringify() 序列化生命周期与处理流水线步骤

二、精细化过滤与脱敏:replacer 参数的两种形态

很多初学者在提交表单或上报埋点时,需要移除敏感字段(例如密码、临时 token 或冗余的 UI 状态)。常规做法是在序列化前手动 delete 属性,但这会产生克隆开销或破坏原对象。合理使用 replacer 参数,即可在序列化管道内部无副作用地完成清洗。

形态一:白名单数组 (Array Filter)

当 replacer 是一个字符串或数字组成的数组时,只有包含在数组中的属性键才会被输出到最终的 JSON 字符串中。未在数组中的属性会被直接剔除。

const account = {
  id: 42,
  username: "developer_01",
  passwordHash: "e10adc3949ba59abbe56e057f20f883e",
  token: "eyJhbGciOiJIUzI1NiIsIn...",
  email: "dev@example.com"
};

// 仅保留 id, username, email 三个公开字段
const safeJson = JSON.stringify(account, ["id", "username", "email"]);
console.log(safeJson);
示例输出
"{"id":42,"username":"developer_01","email":"dev@example.com"}"

注意:白名单数组的属性排列顺序决定了序列化后键的出现顺序;且白名单只对普通对象的属性名称生效,数组内部的索引项不受白名单列表约束。

形态二:递归转换函数 (Callback Replacer)

当 replacer 为函数时,函数接收两个参数 (key, value)。序列化引擎将先针对整个根对象执行一次调用,随后自顶向下递归访问对象的每个属性及嵌套对象的每个键值对。

  • 如果返回普通数据(数字、字符串、布尔值或新对象),该返回值将取代原始值进行序列化;
  • 如果返回 undefined,该属性将被彻底从结果中丢弃;
  • 通过这一特性,可以完成动态脱敏、格式转换与深度剪裁。
const sensitivePayload = {
  orderId: "ORD-2026-9901",
  amount: 288.5,
  bankCard: "6222021234567890",
  internalSecret: "SYS_DEBUG_ONLY"
};

const sanitizedJson = JSON.stringify(sensitivePayload, (key, value) => {
  // 首次调用时 key 为 "",value 为 sensitivePayload 本身,必须放行
  if (key === "internalSecret") {
    return undefined; // 剔除内部调试属性
  }
  if (key === "bankCard" && typeof value === "string") {
    return value.slice(0, 4) + "********" + value.slice(-4); // 银行卡脱敏
  }
  return value; // 其余字段原样保留
}, 2);

console.log(sanitizedJson);
示例输出
{
  "orderId": "ORD-2026-9901",
  "amount": 288.5,
  "bankCard": "6222********7890"
}
重点警告:首层调用的空键特性

在序列化开始时,replacer 函数接收到的第一个键是空字符串 "",其对应的 value 是待序列化的整个根对象。如果代码中不加甄别地写下类似 if (value) return value.toString() 的强转逻辑,会导致整个根对象被误处理。编写函数时,应当先处理特定目标 key,其余情况默认 return value。

JS对象转JSON字符串:JSON.stringify()用法详解
图 2:replacer 参数的双重形态——白名单数组与递归回调函数机制对照

三、特殊数据类型的序列化边界与规整机制

JSON 规范只支持 string、number、boolean、null、object 以及 array 六种基础数据形态。JavaScript 丰富的运行时对象在经过 JSON.stringify() 转化时,会触发一系列内置的规整规则。若不熟悉这些边界,极易引发生产环境数据丢失或逻辑分支异常。

1. undefined、函数与 Symbol 的三种不同待遇

由于 JSON 没有 undefined、函数或 Symbol 的概念,序列化引擎会依据这三者所处的位置采取完全不同的处理策略:

  • 作为非数组对象的属性值时: 这些键值对会被直接忽略,生成的结果中不再包含该属性。
  • 作为数组的元素时: 为了保证数组索引位置与长度不发生偏移,它们会被自动替换为 null。
  • 单独作为基础值进行序列化时: JSON.stringify(undefined) 不返回字符串,而是直接返回 JavaScript 原生字面量 undefined。
// 1. 在对象中:直接丢弃
const objWithSpecial = {
  a: "hello",
  b: undefined,
  c: function() { return 1; },
  d: Symbol("token")
};
console.log(JSON.stringify(objWithSpecial));
// 示例输出: "{"a":"hello"}"

// 2. 在数组中:转为 null 占位
const arrWithSpecial = ["hello", undefined, function() {}, Symbol("sym")];
console.log(JSON.stringify(arrWithSpecial));
// 示例输出: "["hello",null,null,null]"

// 3. 单独序列化:返回原生 undefined
console.log(JSON.stringify(undefined) === undefined); // true
console.log(JSON.stringify(function() {}) === undefined); // true

2. 非有限数值:NaN、Infinity 与 -Infinity

JSON 规范不支持 NaN 和无穷大数值。无论是作为对象属性、数组元素还是单独转换,NaN、Infinity 和 -Infinity 都会统一被规整为 null:

const mathObj = {
  val1: NaN,
  val2: Infinity,
  val3: -Infinity
};
console.log(JSON.stringify(mathObj));
// 示例输出: "{"val1":null,"val2":null,"val3":null}"

3. Date、RegExp、Map 与 Set 的表现

  • Date 实例: Date.prototype 原生实现了 toJSON() 方法,因此序列化时会自动转为 ISO 格式的字符串(例如 "2026-11-18T11:15:00.000Z")。
  • RegExp、Error、Map、Set: 由于它们自身的可枚举自身属性通常为空,默认会被序列化为普通的空对象 {}。如果需要传输 Map 或 Set,必须在序列化前将其转为普通数组或字面量对象。

4. BigInt 类型的阻断报错

尝试直接序列化包含 BigInt 值的对象时,运行时不会进行静默转换,而是会直接抛出致命错误:

const bigData = { id: 100n };
try {
  JSON.stringify(bigData);
} catch (err) {
  console.error(err); // TypeError: Do not know how to serialize a BigInt
}

修复方案: 可通过 replacer 函数将 BigInt 转为字符串,或者给 BigInt.prototype.toJSON 挂载转换实现:

const safeBigJson = JSON.stringify(bigData, (key, value) =>
  typeof value === "bigint" ? value.toString() : value
);
// 示例输出: "{"id":"100"}"
JS对象转JSON字符串:JSON.stringify()用法详解
图 3:JavaScript 特殊数据类型序列化行为与边界对照表

四、自定义序列化行为:toJSON() 协议

如果一个对象定义了名为 toJSON 的方法,JSON.stringify() 在序列化该对象时会优先调用该方法,并将其返回值作为序列化的实际内容。这种机制类似于许多面向对象语言中的自定义序列化接口。

1. toJSON 方法的优先级与执行机制

当目标对象拥有 toJSON 方法时,它的执行次序处于流水线的最前列。系统会将 toJSON() 返回的结果进一步提交给 replacer 和格式化引擎处理。

class Order {
  constructor(id, price, internalCost) {
    this.id = id;
    this.price = price;
    this._internalCost = internalCost;
  }

  // 自定义序列化接口
  toJSON() {
    return {
      orderId: this.id,
      finalPrice: "$" + this.price.toFixed(2),
      isPaid: true
    };
  }
}

const order = new Order("A-102", 99.5, 45);
console.log(JSON.stringify(order, null, 2));
示例输出
{
  "orderId": "A-102",
  "finalPrice": "$99.50",
  "isPaid": true
}

通过实现 toJSON(),类内部的私有数据 _internalCost 被彻底隐藏,而对外暴露的数据格式得到了严格封装。

五、常见报错与生产陷阱排查

陷阱一:循环引用报错 (Circular Structure)

当一个对象中的某个属性直接或间接地引用了该对象本身时,序列化递归引擎会陷入无限死循环。ECMAScript 规范为此设置了防线,检测到引用环时会立即抛出 TypeError: Converting circular structure to JSON。

const nodeA = { name: "Node A" };
const nodeB = { name: "Node B" };
nodeA.sibling = nodeB;
nodeB.sibling = nodeA; // 形成循环引用

// 直接调用会崩溃:
// JSON.stringify(nodeA); // TypeError: Converting circular structure to JSON

通用健壮解决方案: 利用 WeakSet 记录遍历过的对象引用,在遇到二次访问时剪除引用:

function getSafeStringify() {
  const seen = new WeakSet();
  return (key, value) => {
    if (typeof value === "object" && value !== null) {
      if (seen.has(value)) {
        return "[Circular]"; // 剪断循环引用环
      }
      seen.add(value);
    }
    return value;
  };
}

const safeCircularJson = JSON.stringify(nodeA, getSafeStringify(), 2);
console.log(safeCircularJson);
示例输出
{
  "name": "Node A",
  "sibling": {
    "name": "Node B",
    "sibling": "[Circular]"
  }
}

陷阱二:不可滥用 JSON 进行深拷贝

在 JavaScript 中,开发者常使用 JSON.parse(JSON.stringify(obj)) 实现对象的深拷贝。然而基于前文详述的边界规整规则,这种操作存在严重的数据失真隐患:

  1. 对象中的函数(方法)、undefined 以及 Symbol 属性会被直接剔除;
  2. Date 对象转换后会降级为普通 ISO 字符串,反序列化后不再是 Date 实例;
  3. RegExp、Error、Set、Map 会被压成空对象 {};
  4. 一旦包含循环引用,程序会立刻抛错中断。

现代浏览器与 Node.js 17+ 环境中,应优先使用平台原生的 structuredClone() 进行安全深拷贝。

JS对象转JSON字符串:JSON.stringify()用法详解
图 4:JSON.stringify() 全景特性、高频实战场景与防坑指南速查

六、总结与关键决策速查

掌握 JSON.stringify() 的精髓在于理解其“参数协同”与“类型规整”机制。在日常开发中,可以依照以下决策清单进行判断:

  • 日常传输: 直接使用 JSON.stringify(data),输出紧凑体积最小的 JSON 文本。
  • 排版调试与文件写入: 传入第三个参数 space = 2,生成格式清晰的多层级缩进。
  • 属性筛选与脱敏: 优先使用数组白名单 replacer;复杂场景使用函数 (key, value),并谨记首层空键判定与返回 undefined 的剔除效应。
  • 特殊类型保全: 序列化前排查 BigInt、Map、Set,必要时提供类内置的 toJSON() 钩子保证序列化契约。
作者最新文章
相关文章
更多