replacer参数可接收数组或函数:数组实现字段名白名单静态筛选,函数支持动态过滤、修改值及嵌套递归处理,需注意null/undefined显式判断、避免误删0/false、防止循环引用。

replacer 参数接收什么类型值
JSON.stringify 的第二个参数 replacer 可以是数组或函数。传数组时,它只保留键名在该数组中的字段;传函数时,则能动态决定每个键值对是否保留、是否修改值。
常见错误是以为数组形式能做条件过滤——其实不行,它只是白名单式静态筛选。比如 ["name", "age"] 会强制只输出这两个字段,不管它们的值是否为 null 或 undefined。
- 数组用法适合字段名固定、结构已知的简单过滤
- 函数用法才能实现“值为
undefined就跳过”“只保留字符串长度 > 0 的字段”这类逻辑 - 函数中返回
undefined或不返回任何值,该属性会被忽略(不是转成null)
用 replacer 函数过滤掉 undefined / null 值
默认情况下 JSON.stringify 会把 undefined、函数、Symbol 转为 undefined 并直接丢弃,但 null 会被保留。如果想一并过滤 null,必须用 replacer 函数手动拦截。
注意:replacer 函数的 this 指向父对象,key 是字符串(包括 "" 表示根对象),value 是当前字段原始值。
const obj = { a: 1, b: null, c: undefined, d: "ok" };
JSON.stringify(obj, (key, value) => {
if (value === null || value === undefined) return undefined;
return value;
});
// → '{"a":1,"d":"ok"}'
- 不能直接写
if (!value) return undefined,否则0、false、""也会被误删 - 对嵌套对象,该函数会递归调用每一层,所以无需额外处理深层结构
- 若需保留
0和false,但排除null和undefined,必须显式比对
按字段名前缀动态过滤(比如剔除所有 _ 开头的私有字段)
有些对象带内部字段(如 _id、_meta),导出 JSON 时不想暴露。replacer 函数可通过 key 字符串判断,灵活控制。
const user = { name: "Alice", _token: "x123", email: "a@b.c", _cache: {} };
JSON.stringify(user, (key, value) => key.startsWith("_") ? undefined : value);
// → '{"name":"Alice","email":"a@b.c"}'
- 注意:根对象的
key是空字符串"",不会匹配startsWith("_"),所以不影响整体 - 如果字段名本身含 Unicode 或特殊字符,
startsWith仍可靠;但避免用indexOf手动判断,易漏边界 - 这种过滤发生在序列化过程中,不修改原对象,安全
replacer 函数里修改值(不只是过滤)
replacer 不仅能删字段,还能改值——比如统一格式化日期、脱敏手机号、转换 BigInt。只要返回非 undefined 值,就会替代原值参与序列化。
容易忽略的是:返回值会被再次传入 replacer(如果还有子属性),形成递归处理链。所以别返回一个未处理过的复杂对象,否则可能无限循环或意外触发多次处理。
- 返回基本类型(
string/number/boolean/null)最安全 - 若需返回对象,确保它不含循环引用,且字段名不触发新的过滤逻辑(比如你过滤
_开头字段,就别在返回对象里再塞一个_temp) - 对
Date对象,可直接返回value.toISOString();对BigInt,必须显式转成string或number,否则报错
真正难的不是写对 replacer,而是想清楚「哪些字段该留、哪些该改、哪些该删」——这个逻辑一旦嵌套变深或规则变多,函数体就容易失控。建议把过滤逻辑拆成独立小函数,比如 shouldKeep(key, value) 和 normalizeValue(value),再组合进 replacer。


















