Learn JavaScript
Справочник / JSON.stringify()

JSON.stringify() - преобразование значения в JSON-строку в JavaScript

JSON.stringify() превращает значение JavaScript в JSON-строку.

Чаще всего его используют, когда нужно:

  • сохранить данные в localStorage
  • отправить объект на сервер
  • превратить объект в строку для хранения или передачи

Синтаксис

Базовая запись выглядит так:

JSON.stringify(value, replacer, space)

Где:

  • value - значение, которое нужно превратить в JSON-строку
  • replacer - необязательная настройка для отбора или преобразования свойств
  • space - необязательная настройка для красивого форматирования строки

Что возвращает JSON.stringify()

Метод возвращает строку.

const user = {
  name: "Анна",
  age: 25,
};

const json = JSON.stringify(user);

console.log(json);
// '{"name":"Анна","age":25}'

console.log(typeof json); // "string"

Это важно: результатом будет именно строка, а не объект.

Пример с объектом

Самый частый сценарий - превратить объект в JSON-строку.

const product = {
  title: "Ноутбук",
  price: 120000,
  inStock: true,
};

console.log(JSON.stringify(product));
// '{"title":"Ноутбук","price":120000,"inStock":true}'

Пример с массивом

Массивы тоже спокойно превращаются в JSON.

const numbers = [1, 2, 3];

console.log(JSON.stringify(numbers));
// "[1,2,3]"

С вложенными структурами это тоже работает.

const data = {
  user: "Анна",
  skills: ["HTML", "CSS", "JavaScript"],
};

console.log(JSON.stringify(data));
// '{"user":"Анна","skills":["HTML","CSS","JavaScript"]}'

JSON.stringify() и красивые отступы

Третий аргумент space позволяет сделать JSON читаемым.

const user = {
  name: "Анна",
  age: 25,
  city: "Москва",
};

console.log(JSON.stringify(user, null, 2));

Результат будет таким:

{
  "name": "Анна",
  "age": 25,
  "city": "Москва"
}

Это особенно удобно для логов, отладки и сохранения данных в более читаемом виде.

Второй аргумент replacer

replacer позволяет управлять тем, какие свойства попадут в итоговую строку.

Например, можно оставить только часть полей:

const user = {
  name: "Анна",
  age: 25,
  password: "123456",
};

console.log(JSON.stringify(user, ["name", "age"]));
// '{"name":"Анна","age":25}'

Такой вариант полезен, когда нужно явно исключить лишние поля.

replacer как функция

Второй аргумент может быть и функцией.

const user = {
  name: "Анна",
  password: "123456",
};

const json = JSON.stringify(user, (key, value) => {
  if (key === "password") {
    return undefined;
  }

  return value;
});

console.log(json);
// '{"name":"Анна"}'

Это уже более гибкий способ управлять сериализацией.

Что происходит со строками, числами и boolean

Примитивы тоже преобразуются в JSON-строку.

console.log(JSON.stringify("JavaScript")); // '"JavaScript"'
console.log(JSON.stringify(123)); // "123"
console.log(JSON.stringify(true)); // "true"
console.log(JSON.stringify(null)); // "null"

Обратите внимание: строка в JSON получает двойные кавычки.

Что происходит с undefined, функциями и Symbol

Здесь есть важный нюанс.

Если такие значения находятся в объекте, они просто не попадут в результат.

const user = {
  name: "Анна",
  age: undefined,
  sayHi() {},
  id: Symbol("id"),
};

console.log(JSON.stringify(user));
// '{"name":"Анна"}'

Если такие значения находятся в массиве, они превращаются в null.

const values = [1, undefined, function () {}, Symbol("id")];

console.log(JSON.stringify(values));
// "[1,null,null,null]"

А если передать такое значение напрямую, результатом будет undefined.

console.log(JSON.stringify(undefined)); // undefined
console.log(JSON.stringify(function () {})); // undefined

Что происходит с NaN и Infinity

Эти значения в JSON напрямую не поддерживаются, поэтому превращаются в null.

console.log(JSON.stringify(NaN)); // "null"
console.log(JSON.stringify(Infinity)); // "null"
console.log(JSON.stringify(-Infinity)); // "null"

То же самое произойдёт и внутри объектов или массивов.

Что происходит с Date

Объект Date превращается в строку.

const date = new Date("2025-01-15T10:00:00Z");

console.log(JSON.stringify(date));
// '"2025-01-15T10:00:00.000Z"'

Если Date лежит внутри объекта, в JSON попадёт именно строка даты.

Ошибка с циклическими ссылками

JSON.stringify() не умеет работать с циклическими ссылками.

const user = {
  name: "Анна",
};

user.self = user;

// JSON.stringify(user); // TypeError

Если объект ссылается сам на себя напрямую или через цепочку, метод выбросит ошибку.

Ошибка с BigInt

BigInt тоже не сериализуется обычным JSON.stringify().

const value = 10n;

// JSON.stringify(value); // TypeError

Это ещё одна частая ловушка, если в данных есть большие целые числа.

JSON.stringify() и String() - не одно и то же

Эти вещи иногда путают.

const user = { name: "Анна" };

console.log(String(user)); // "[object Object]"
console.log(JSON.stringify(user)); // '{"name":"Анна"}'

String() просто делает строковое представление значения.

JSON.stringify() строит JSON-строку по правилам JSON.

Когда это полезно

JSON.stringify() особенно удобен, когда:

  • нужно сохранить объект в localStorage
  • надо отправить данные на сервер
  • хочется вывести объект в читаемом виде
  • нужно превратить массив или объект в строку для хранения

Пример с localStorage:

const settings = {
  theme: "dark",
  lang: "ru",
};

localStorage.setItem("settings", JSON.stringify(settings));

Частые ошибки

Думать, что метод возвращает объект

const user = { name: "Анна" };
const result = JSON.stringify(user);

console.log(typeof result); // "string"

Результат - строка, а не объект.

Путать JSON-строку и обычную строку

console.log(JSON.stringify("JavaScript"));
// '"JavaScript"'

Внутри JSON строковые значения записываются в двойных кавычках.

Ожидать, что undefined сохранится как есть

const user = {
  name: "Анна",
  age: undefined,
};

console.log(JSON.stringify(user));
// '{"name":"Анна"}'

Свойства со значением undefined в объекте просто исчезают.

Забывать про циклические ссылки

const obj = {};
obj.self = obj;

// JSON.stringify(obj); // TypeError

Если в данных есть ссылка на самих себя, метод не сработает.

Использовать JSON.stringify() как глубокую копию “на все случаи”

Иногда так делают:

const copy = JSON.parse(JSON.stringify(data));

Для простых данных это может сработать, но при Date, undefined, BigInt, функциях, Infinity и других особых значениях результат будет искажён или вообще приведёт к ошибке.

Быстрая памятка

  • JSON.stringify() превращает значение JavaScript в JSON-строку
  • результатом почти всегда будет строка
  • третий аргумент space добавляет красивые отступы
  • второй аргумент replacer позволяет фильтровать или менять значения
  • undefined, функции и Symbol в объектах пропускаются
  • undefined, функции и Symbol в массивах превращаются в null
  • NaN и Infinity превращаются в null
  • циклические ссылки вызывают ошибку
  • BigInt обычный JSON.stringify() не поддерживает

Коротко

JSON.stringify() в JavaScript нужен, чтобы превратить объект, массив или другое значение в JSON-строку. Главное, что стоит запомнить: это очень полезный метод для хранения и передачи данных, но у него есть важные ограничения с undefined, функциями, циклическими ссылками и BigInt.

← length - свойство с количеством параметров функции в JavaScript
JSON.parse() - преобразование JSON-строки в значение JavaScript →