JS对象转JSON字符串:JSON.stringify()用法详解
深入解析JavaScript中JSON.stringify()的完整用法,系统讲解语法三参数、replacer过滤机制、space格式化排版、特殊数据类型序列化边界以及循环引用等常见陷阱与解决方案。
将 JavaScript 内存中的对象转换为符合 JSON 格式的文本字符串,最直接且标准的方法是调用内置方法 JSON.stringify()。在实际业务中,除了基础的数据序列化外,开发者常常需要过滤敏感字段、对输出结果进行排版美化,以及安全应对 undefined、函数或循环引用带来的丢失与报错问题。本文将全面拆解该方法的三个参数、执行原理、特殊类型边界行为与高频避坑实践。
一、基础语法与三个核心参数拆解
在 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 为数字时,取值范围为 1 至 10,如果传入大于 10 的数值,引擎将强制截断为 10;如果传入非空字符串(例如 " " 或 "--"),该字符串的前 10 个字符将被作为每一层缩进的填充前缀。
二、精细化过滤与脱敏: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。
三、特殊数据类型的序列化边界与规整机制
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"}"
四、自定义序列化行为: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)) 实现对象的深拷贝。然而基于前文详述的边界规整规则,这种操作存在严重的数据失真隐患:
- 对象中的函数(方法)、
undefined以及Symbol属性会被直接剔除; Date对象转换后会降级为普通 ISO 字符串,反序列化后不再是 Date 实例;RegExp、Error、Set、Map会被压成空对象{};- 一旦包含循环引用,程序会立刻抛错中断。
现代浏览器与 Node.js 17+ 环境中,应优先使用平台原生的 structuredClone() 进行安全深拷贝。
六、总结与关键决策速查
掌握 JSON.stringify() 的精髓在于理解其“参数协同”与“类型规整”机制。在日常开发中,可以依照以下决策清单进行判断:
- 日常传输: 直接使用
JSON.stringify(data),输出紧凑体积最小的 JSON 文本。 - 排版调试与文件写入: 传入第三个参数
space = 2,生成格式清晰的多层级缩进。 - 属性筛选与脱敏: 优先使用数组白名单
replacer;复杂场景使用函数(key, value),并谨记首层空键判定与返回undefined的剔除效应。 - 特殊类型保全: 序列化前排查
BigInt、Map、Set,必要时提供类内置的toJSON()钩子保证序列化契约。
怎么在JS数组指定位置插入元素?splice方法实战
2026-11-20 14:52:19
JavaScript闭包为何会延长变量生命周期?原理与实战解析
2026-11-20 14:31:25
JSONP实现JS跨域的原理、局限性与现代替代方案
2026-11-20 14:13:28
JS使用for循环处理稀疏数组与类数组对象的方法
2026-11-20 12:22:36
JS回调函数中的this指向丢失怎么办?bind/call/apply解决方案
2026-11-20 11:50:53





![为什么JS对象直接转字符串显示[object Object]](https://img.javascript.cn/tit/articles/13236/20261106/84aa86eb15b66540a3d64b4a7a62b181d4058395daf4aec8f716e9fa4f562f53.webp)


