JavaScript中的JSON.stringify有哪些参数可以定制？

在JavaScript开发中，把对象转换成字符串是一项非常基础的操作。绝大多数人只写过JSON.stringify(obj)这种最简形式，却不知道这个方法完整签名包含三个参数：value、replacer和space。通过合理利用后两个参数，我们可以过滤掉不需要的字段、转换特殊数据类型、甚至美化输出格式。下面从参数构成、replacer用法以及space格式化三个维度来详细拆解。

一、JSON.stringify的完整参数结构

标准语法中，JSON.stringify接收三个参数。第一个是必填的待序列化值；第二个replacer可以是函数或数组，用来筛选和转换；第三个space控制缩进。很多运行时错误其实源于不了解这些参数的存在，例如对象里出现循环引用时，不借助replacer做处理就会直接抛出TypeError。

当replacer为null或undefined时，相当于不传，所有可枚举自有属性都会被序列化。如果传入数组，则只有数组里列出的键名会出现在结果中，这非常适合做接口字段白名单。若传入函数，则每个键值对都会经过该函数，返回值决定最终写入的内容。space参数则纯粹影响可读性，不影响数据本身。

从底层实现看，序列化过程会递归遍历对象。遇到基本类型直接转文本；遇到对象会先调用replacer（若有），再读取toJSON方法（若定义），最后按space规则拼接。理解这个顺序，才能预测复杂对象的最终输出形态，而不是靠试错。

二、replacer函数的进阶用法

replacer作为函数时，签名是function(key, value)，在遍历时从最内层向外层调用，最终还会以空字符串为key调用一次根值。我们可以利用它过滤敏感字段，比如把密码或token替换为undefined，这样它们就不会出现在字符串里。

下面的例子演示了如何隐藏password并转换Date为时间戳：

var user = {
  name: '张三',
  password: '123456',
  birth: new Date('1990-01-01'),
  role: 'admin'
};

var str = JSON.stringify(user, function(key, value) {
  if (key === 'password') {
    return undefined; // 过滤掉密码
  }
  if (value instanceof Date) {
    return value.getTime(); // 日期转时间戳
  }
  return value;
}, 2);

console.log(str);

上述代码中，当key为password时返回undefined，该属性被完全忽略。而birth值经过判断后转成了数字时间戳，避免了ISO字符串的冗长。这种写法比先深拷贝再删除属性要简洁得多，也避免了修改原对象。

除了函数，replacer数组也很有用。比如只想保留name和role：

var allowed = ['name', 'role'];
var str2 = JSON.stringify(user, allowed, 2);
console.log(str2);

数组形式不支持值转换，只能做键名白名单，但性能略好且意图清晰。在对外提供API响应裁剪时，数组方式更安全，因为新增字段默认不会泄露，除非显式加入白名单。

三、space参数与格式化输出

space参数可以是数字或字符串。数字表示每层缩进的空格数，最大有效值为10；字符串则使用该字符串作为缩进符，最长取前十个字符。设置space后，输出会从单行变为多行带缩进，非常适合日志存储或配置文件生成。

对比下面两段代码，前者无space，后者space为4：

var data = { a: 1, b: { c: 2 } };
console.log(JSON.stringify(data));
// 输出: {"a":1,"b":{"c":2}}

console.log(JSON.stringify(data, null, 4));
// 输出:
// {
//     "a": 1,
//     "b": {
//         "c": 2
//     }
// }

在调试时，带缩进的输出能让人快速定位结构问题。但如果用于网络传输，多余空格会增加带宽，此时应传null。另外，space不影响replacer逻辑，两者可叠加使用。实际项目中，建议封装一个logger函数，统一用2空格序列化对象，既可读又不过于膨胀。

还需要注意，space仅对对象、数组生效，对顶层基本类型无影响。若传入字符串缩进如t，某些老版本解析器可能显示异常，但现代浏览器均支持。合理利用这三个参数，JSON.stringify就从黑盒工具变成了可精细调控的序列化器。

JSON.stringifyJavaScript序列化replacer函数修改时间：2026-08-18 07:36:25