详解JavaScript使用JSON.stringify将对象转换为JSON字符串的基础语法、replacer过滤与space缩进参数、数据类型转换规则、常见报错处理及结果验证方法。
JS使用JSON.stringify将对象转换为JSON字符串
时间:2026-11-17
浏览:121
文章目录
在 JavaScript 中,把内存里的对象转换为标准的 JSON 字符串,直接使用内置方法 JSON.stringify(value, replacer, space) 即可完成。它既能把普通对象序列化为紧凑的文本用于接口请求和本地存储,也能通过可选参数筛选字段或输出带缩进的易读文本。下面按基本用法、参数控制、类型转换规则、常见报错处理及结果验证的顺序详细说明。
一、基础语法与最简转换步骤
JSON.stringify 是全局对象 JSON 上的静态方法,在浏览器控制台(F12 开发者工具的 Console 面板)以及 Node.js 环境中都可直接调用,不需要额外引入第三方包。
它接收三个参数,其中只有第一个参数是必填的:
JSON.stringify(value[, replacer[, space]])
value:需要转换的 JavaScript 值,通常是普通对象或数组。replacer(可选):用于筛选或转换属性的函数,或者指定保留属性名的数组。space(可选):用于控制结果字符串缩进的空格数或前缀字符串。
把一个简单对象转为 JSON 字符串时,只需传入该对象即可。以下代码可在浏览器控制台或 Node.js 中直接执行:
const user = {
id: 101,
name: '林青',
active: true,
tags: ['前端', '文档']
};
const jsonStr = JSON.stringify(user);
console.log(typeof jsonStr);
console.log(jsonStr);
从输出可以看到两个重要变化:第一,原本不带引号的键名(如 id、name)以及单引号字符串(如 '林青'),全部被转换成了 JSON 规范要求的双引号;第二,默认输出没有多余空格和换行,适合直接用于网络传输。
二、用第二个和第三个参数控制字段与格式
在实际业务中,直接把整个对象原封不动转成一行字符串并不总是合适。比如提交表单时要剔除临时状态字段,或者记录日志时希望 JSON 自动换行对齐。这时就需要用到 replacer 和 space 参数。
1. 使用 replacer 数组作为属性白名单
如果只需要保留对象中的某几个字段,可以把允许保留的键名放进数组,作为第二个参数传入。输出结果的键顺序也会与该数组保持一致:
const profile = {
id: 204,
username: 'chen_ming',
passwordHash: 'e10adc3949ba59abbe56e057f20f883e',
email: 'chen@example.com'
};
const safeJson = JSON.stringify(profile, ['id', 'username']);
console.log(safeJson);
需要注意,当 value 包含嵌套对象时,数组白名单对嵌套对象的所有层级同样生效。如果嵌套对象内部的键名没有列在数组中,这些嵌套属性也会被一并过滤掉。
2. 使用 replacer 函数动态过滤或改写值
当过滤条件需要按值判断,或者只排除少数几个敏感字段时,传入函数比写全量白名单更灵活。replacer(key, value) 会针对根对象以及每一层属性依次调用:
- 函数返回
undefined时,对应的属性不会出现在最终的 JSON 字符串中(若位于数组元素中,该位置会变成null)。 - 函数返回其他值时,该返回值会替代原值参与序列化。
- 第一次调用时,
key是空字符串"",value是最外层对象本身,务必把根对象返回出去,否则整个结果会直接变成undefined。
const order = {
orderNo: 'ORD-2026-08',
amount: 299,
internalNote: '测试订单勿发',
token: 'secret-xyz'
};
const filteredJson = JSON.stringify(order, (key, val) => {
if (key === 'internalNote' || key === 'token') {
return undefined;
}
return val;
});
console.log(filteredJson);
3. 使用 space 参数格式化缩进
第三个参数 space 专门用于控制空白排版,不改变数据内容。如果只为了传 space 而不需要过滤字段,第二个参数传 null 即可:
- 传入数字(如
2或4):每层缩进对应数量的空格。规范规定上限为 10,传入大于 10 的数字也会按 10 个空格处理,小于 1 则无缩进。 - 传入字符串(如
"\t"或" "):使用该字符串作为每一级的缩进前缀,同样最多截取前 10 个字符。
const config = {
host: '127.0.0.1',
port: 8080,
features: ['gzip', 'cache']
};
console.log(JSON.stringify(config, null, 2));
三、不同数据类型在转换时的行为规则
JavaScript 对象里可以存放函数、undefined、日期甚至不可枚举属性,但 JSON 格式本身只支持字符串、有限数字、布尔值、null、数组和普通键值对这 6 类数据。因此,JSON.stringify 在遍历对象时会按固定规则对非标准类型做裁剪或转换。
| JS 数据类型 / 特性 | 作为对象属性值时 | 作为数组元素时 |
|---|---|---|
字符串、有限数字、布尔值、null |
按标准 JSON 格式保留 | 按标准 JSON 格式保留 |
undefined、函数、Symbol |
整个键值对会被直接忽略 | 转换为 null 占位 |
NaN、Infinity、-Infinity |
转换为 null |
转换为 null |
Date 对象 |
自动调用 toJSON(),转为 ISO 字符串 |
自动调用 toJSON(),转为 ISO 字符串 |
Symbol 作为键名 |
该属性被完全忽略 | 不适用(数组下标为数字) |
| 不可枚举属性 / 原型链继承属性 | 只序列化自身可枚举属性,其余忽略 | 非索引扩展属性同样被忽略 |
下面通过一段示例验证对象属性与数组元素在处理 undefined、函数、NaN 和 Date 时的差异:
const sample = {
title: '任务清单',
count: NaN,
optional: undefined,
run: function () { return 1; },
createdAt: new Date('2026-05-01T08:00:00.000Z'),
items: ['文档', undefined, () => {}, Symbol('tag')]
};
console.log(JSON.stringify(sample));
如果对象自身定义了 toJSON() 方法,JSON.stringify 会优先使用该方法的返回值来进行转换,而不是直接序列化原对象的所有字段。自定义类或需要隐藏内部结构的数据对象常利用这一机制控制序列化结果:
const session = {
userId: 88,
secretKey: 'private-key',
toJSON() {
return { userId: this.userId };
}
};
console.log(JSON.stringify(session));
Map、Set、RegExp 对象虽然在 JavaScript 中属于对象,但它们默认没有可枚举的普通数据属性,直接传给 JSON.stringify 会得到空对象字符串 "{}"。如需序列化 Map 或 Set,应先通过 Object.fromEntries(map) 或 Array.from(set) 转为普通对象或数组后再调用。
四、常见报错与数据丢失的处理方法
日常调用 JSON.stringify 时,最容易遇到两类运行报错(TypeError)以及一类隐性数据丢失问题。
1. 循环引用报错(Converting circular structure to JSON)
当对象的某个子属性又指向了自身或祖先节点时(例如双向链表、带 parent 引用的树节点、某些 DOM 对象),JSON.stringify 会立刻抛出 TypeError。
如果确实需要序列化这类对象,可以在 replacer 函数里配合 WeakSet 记录已经遍历过的对象引用,遇到重复引用的对象时返回 undefined 跳过:
function safeStringify(obj, space = 0) {
const seen = new WeakSet();
return JSON.stringify(
obj,
(key, value) => {
if (typeof value === 'object' && value !== null) {
if (seen.has(value)) {
return undefined;
}
seen.add(value);
}
return value;
},
space
);
}
const node = { name: 'root' };
node.self = node;
console.log(safeStringify(node));
需要注意的是,WeakSet 只防止同一祖先路径或重复引用的对象引发死循环;如果两个不同属性恰好共享同一个非循环的子对象,上述写法会把第二次出现的引用忽略掉。若只想拦截真正的祖先环,可以在递归前手动剥离已知的父级引用字段(如 parent)。
2. BigInt 无法直接序列化
对象中包含大整数(如 12345678901234567890n)时,直接调用会报错 Do not know how to serialize a BigInt。通用做法是在 replacer 中把 BigInt 转成字符串,避免精度丢失:
const record = { id: 9007199254740993n, status: 'ok' };
const jsonText = JSON.stringify(record, (key, value) =>
typeof value === 'bigint' ? value.toString() : value
);
console.log(jsonText);
3. 区分“普通拷贝”与序列化副作用
有些开发者习惯用 JSON.parse(JSON.stringify(obj)) 做深拷贝,但这种写法只适用于纯数据对象。只要原对象里包含函数、undefined、Date(反序列化后会变成字符串而非 Date 实例)或正则表达式,转换后结构就会发生变化。仅需要做数据持久化或网络传输时使用 JSON.stringify 才是最稳妥的。
五、典型使用场景与结果验证
将对象转为 JSON 字符串后,最常见的两个落地场景是浏览器本地存储和 HTTP 接口提交:
- 写入 localStorage:
localStorage.setItem(key, value)只接受字符串。直接存对象会变成"[object Object]",必须先用JSON.stringify序列化:const settings = { theme: 'light', pageSize: 20 }; localStorage.setItem('app_settings', JSON.stringify(settings)); - 发送 POST 请求体:使用
fetch提交 JSON 数据时,将对象序列化后赋给body,同时在请求头声明Content-Type: application/json:fetch('/api/users', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: '林青', role: 'editor' }) });
完成转换后,可以通过两步确认结果符合预期:首先检查返回值类型是否为 'string'(防止因入参是 undefined 或 replacer 未返回根对象而得到 undefined);其次在调试阶段可以用 JSON.parse(result) 还原一次,核对保留下来的字段、嵌套结构和数据类型是否与预期一致。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。