Что такое Symbol в JavaScript — и почему JSON.stringify его не видит

Положи в объект поле с ключом-символом и отправь его на сервер:
const id = Symbol('id')
const user = { name: 'Аня', [id]: 42 }
JSON.stringify(user) // '{"name":"Аня"}'
Object.keys(user) // ['name']
Поле на месте — user[id] вернёт 42. Но JSON его не видит. Object.keys тоже. Это не баг. Это ровно то, ради чего символы придумали. Давай разберёмся, что это за штука и где ты её уже встречал, сам того не зная.
Что такое Symbol простыми словами
Symbol — это значение, которое гарантированно уникально. Каждый вызов Symbol() создаёт новое, ни на что не похожее:
Symbol('id') === Symbol('id') // false
Строка в скобках — просто подпись для отладки. Она не делает символы равными. Две таблички «ключ от подвала» не превращают два разных ключа в один.
Главное применение — ключ свойства в объекте. Обычный ключ — строка. Любой код может случайно написать user.id и затереть твоё поле. Символьный ключ так не затрёшь. До него доберётся только тот, у кого в руках сам символ.
Ещё одна особенность: typeof Symbol() вернёт 'symbol'. Это отдельный примитивный тип, как строка или число. И new Symbol() не сработает — будет TypeError.
Почему его не видят JSON и Object.keys
Символьные ключи спрятаны от обычного перебора. Их пропускают:
JSON.stringify— поле просто исчезает из результата;Object.keys,Object.values,Object.entries;- цикл
for...in.
Зато они не пропали. Найти их можно специальными способами:
Object.getOwnPropertySymbols(user) // [Symbol(id)]
Reflect.ownKeys(user) // ['name', Symbol(id)]
И одна ловушка в обратную сторону. Spread ...user и Object.assign символьные ключи копируют. Скопировал объект — служебное поле поехало с ним. Отправил по сети — оно отвалилось.
Отсюда практичное правило. Символ хорош для служебной метки, которая не должна утечь в JSON. А вот для данных, которые ты сохраняешь или отправляешь, он не годится — они молча пропадут. Подробнее про устройство ключей — в статье про объекты.
Ошибка, на которой спотыкаются все
Символ не умеет сам превращаться в строку:
'Пользователь ' + id // TypeError: Cannot convert a Symbol value to a string
`ключ: ${id}` // та же ошибка
Число склеится. null склеится. Даже объект склеится в [object Object]. А символ — нет, падает сразу. Сделано специально: чтобы уникальный ключ случайно не превратился в обычную строку и не потерял уникальность.
Если тебе просто нужно его показать, есть два честных способа:
String(id) // 'Symbol(id)'
id.description // 'id'
Увидел в логе Cannot convert a Symbol value to a string — ищи место, где значение склеивается с текстом. Часто это console.log('...' + key) в цикле по Reflect.ownKeys.
Где ты уже пользуешься символами
Вот неожиданная часть. Ты работаешь с символами каждый день — просто встроенными.
for...of. Почему массив можно перебрать через for...of, а обычный объект нет? У массива есть метод с ключом Symbol.iterator. Цикл ищет именно его. У обычного объекта такого метода нет, отсюда ошибка TypeError: obj is not iterable. Подробнее про сами циклы — в статье про циклы.
React и защита от подделки. У каждого React-элемента есть служебное поле $$typeof. В нём лежит символ: Symbol.for('react.element'), а в React 19 — Symbol.for('react.transitional.element'). Зачем? JSON не умеет хранить символы. Значит, объект, пришедший с сервера как JSON, не может притвориться React-элементом. Если злоумышленник подсунет в данные «готовый элемент», React его просто не отрисует.
Другие «хорошо известные» символы. Symbol.asyncIterator работает в for await — им читают стриминговые ответы нейросетей. Symbol.toPrimitive решает, во что объект превратится в +obj. А Symbol.toStringTag отвечает за подпись в [object Map].
Symbol() или Symbol.for()
Иногда уникальность мешает. Например, один модуль ставит метку, а другой — из другой библиотеки или iframe — должен её узнать. Для этого есть глобальный реестр:
Symbol.for('app.id') === Symbol.for('app.id') // true
Symbol.for ищет символ по имени. Нет такого — создаёт и запоминает. Именно так React узнаёт свои элементы, даже если на странице две копии библиотеки.
Короткое правило:
- нужна метка, которую никто не повторит, —
Symbol('…'); - нужна метка, о которой договорились разные части кода, —
Symbol.for('…'), и называй её с префиксом, как'myapp.id'.
Нужно ли новичку писать свои символы?
Чаще всего нет. В обычном приложении хватает строковых ключей. Но понимать символы полезно: они объясняют for...of, $$typeof в React и странные ошибки при склейке строк.
Почему поле с символом пропало после сохранения?
Потому что JSON.stringify пропускает символьные ключи. То же самое с localStorage, fetch с JSON-телом и любой базой через JSON. Храни такие данные под строковым ключом.
Чем символ отличается от строки-ключа?
Строку 'id' может написать любой код и случайно затереть поле. Символ существует в одном экземпляре. Добраться до поля можно только через него, и в обычный перебор оно не попадает.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





