Ошибка JSON Parse Unexpected Token: Полное руководство по исправлению и предотвращению

Вы работаете над проектом, и внезапно всё ломается. В консоли появляется загадочное сообщение: "Unexpected token in JSON at position...". Знакомо? Эта ошибка — один из самых частых кошмаров разработчиков, работающих с JavaScript, API и современными веб-приложениями. Но не паникуйте! В этой статье мы глубоко погрузимся в природу этой ошибки, разберём все возможные причины и, самое главное, научимся её исправлять и предотвращать.

Что такое JSON и почему он так важен?

JSON (JavaScript Object Notation) — это легковесный формат обмена данными, который стал стандартом де-факто для веб-разработки. Он используется повсюду: от передачи данных между клиентом и сервером до конфигурационных файлов. Синтаксис JSON строг и минималистичен: данные представляются в виде пар "ключ-значение", разделённых запятыми и заключённых в фигурные скобки для объектов или квадратные для массивов.

Что означает "Unexpected Token"?

"Token" (лексема) — это минимальная значимая единица в языке. В контексте JSON это могут быть: фигурные скобки { }, квадратные скобки [ ], двоеточия :, запятые ,, кавычки ", а также литералы (строки, числа, true, false, null). Ошибка "Unexpected token" возникает, когда парсер JSON встречает символ или последовательность символов в том месте, где они, согласно спецификации JSON, недопустимы.

Типичные причины ошибки и их решения

1. Лишние или пропущенные запятые

Самая частая причина. JSON не допускает "висячих" запятых после последнего элемента в объекте или массиве.

// НЕПРАВИЛЬНО (лишняя запятая)
{
  "name": "Alex",
  "age": 30,
}

// ПРАВИЛЬНО
{
  "name": "Alex",
  "age": 30
}

2. Неправильные кавычки

JSON допускает только двойные кавычки (") для обозначения строк и ключей. Одинарные кавычки (') или обратные апострофы (`` ` ``) вызовут ошибку.

// НЕПРАВИЛЬНО
{'name': 'Alex'}

// ПРАВИЛЬНО
{"name": "Alex"}

3. Неэкранированные специальные символы в строках

Если внутри строки встречаются символы, которые должны быть экранированы (например, кавычка, обратный слеш, перенос строки), это сломает парсинг.

// НЕПРАВИЛЬНО
{"message": "He said \"Hello\""} // Кавычки внутри строки

// ПРАВИЛЬНО (с экранированием)
{"message": "He said \"Hello\""}

4. Ответ сервера — не JSON

Частая ситуация при работе с API: сервер возвращает HTML-страницу с ошибкой (например, 500 Internal Server Error), пустой ответ или plain text, а ваш код пытается обработать это как JSON.

5. Невидимые символы (BOM, пробелы)

В начале файла может находиться символ BOM (Byte Order Mark), особенно если файл сохранён в кодировке UTF-8 с BOM. Парсер JSON воспримет его как неожиданный токен.

Как отлаживать и исправлять ошибку: Пошаговый план

1. Прочитайте сообщение об ошибке внимательно. Оно указывает позицию (position) проблемного символа. Используйте онлайн-валидаторы JSON (jsonlint.com) или встроенные инструменты разработчика.
2. Проверьте данные «в сыром виде». Выведите строку, которую вы пытаетесь распарсить, в консоль с помощью console.log(responseText) или используйте сетевую вкладку DevTools.
3. Используйте блок try...catch. Всегда оборачивайте вызов JSON.parse() в обработку исключений.

try {
  const data = JSON.parse(jsonString);
  // Работаем с data
} catch (error) {
  console.error("Ошибка парсинга JSON:", error.message);
  console.log("Сырая строка:", jsonString);
}

4. Валидируйте JSON на стороне сервера. Убедитесь, что ваш бэкенд всегда отправляет корректный JSON.
5. Используйте «ленивый» парсинг. Для сложных или ненадёжных источников данных рассмотрите использование более tolerant парсеров или ручной разбор с помощью регулярных выражений (как крайняя мера).

Профилактика лучше, чем лечение

• Используйте линтеры (ESLint) и форматтеры кода (Prettier) в своём проекте.
• Для генерации JSON всегда используйте встроенный метод JSON.stringify(), а не конкатенацию строк вручную.
• При работе с API тщательно изучайте документацию и тестируйте ответы.
• Храните конфигурационные JSON-файлы в репозитории и проверяйте их валидатором перед коммитом.

FAQ (Часто задаваемые вопросы)

Что значит "Unexpected token < in JSON at position 0"?

Это почти наверняка означает, что вы пытаетесь распарсить HTML (который начинается с тега <!DOCTYPE> или <html>) как JSON. Сервер вернул не JSON, а HTML-страницу, возможно, с ошибкой.

Как быстро проверить валидность JSON?

Скопируйте вашу JSON-строку и вставьте на сайт jsonlint.com или используйте встроенный валидатор в редакторе кода (например, VS Code).

Может ли ошибка возникнуть из-за кодировки файла?

Да. Убедитесь, что ваш файл сохранён в кодировке UTF-8 без BOM. Большинство современных редакторов позволяют это проверить и конвертировать.

Я уверен, что JSON правильный, но ошибка остаётся. В чём дело?

Возможно, проблема в невидимых символах или в том, что вы парсите не ту строку. Тщательно проверьте исходные данные с помощью console.log(typeof jsonString) и console.log(jsonString).