כיצד לתקן שגיאות פענוח JSON: בדיקת Unexpected token צעד אחר צעד

שורה תחתונה: הפכו שגיאות JSON.parse לשורה ותו, ואז שללו שישה גורמים: פסיקים עוקבים, גרשיים בודדים, הערות, תווי בקרה, BOM וקיטוע.

מתחילכ-12 דקות קריאהפורסם 2026-10-30עודכן 2026-11-01

שורה תחתונה: בשגיאת פענוח, קראו את השורה והעמודה המדווחות כדי למצוא את התו הבלתי-חוקי הראשון, ואז החליטו אם זה גרש חסר, פסיק חסר, פסיק עוקב, BOM או קיטוע — אל תקראו את כל המסמך מחדש מההתחלה.

הודעת שגיאה אף פעם לא אומרת לכם "מה לא בסדר"; היא רק אומרת "היכן המפענח כבר לא יכול היה להמשיך". שני המיקומים האלה לרוב אינם אותו מקום.

1. תחילה, תרגמו את השגיאה לקואורדינטות

אותו JSON שבור מפיק שגיאות שונות לחלוטין בשפות שונות, אבל את כולן אפשר להמיר ל"איזו שורה, איזה תו":

סביבה	שגיאה אופיינית	איך לקרוא אותה
דפדפן / Node	`Unexpected token } in JSON at position 42`	position הוא היסט תו מבוסס 0, לא מספר שורה
Node 20+	`Unexpected non-whitespace character after JSON at position 42`	פירושו שהחלק הראשון תקין והתוכן הנוסף מתחיל אחרי 42
Java Jackson	`Unexpected character ('}' (code 125)): was expecting ... at [Source: (String)..."..." ; line: 3, column: 1]`	נותן שורה ועמודה ישירות, השימושי מכולם
Python	`json.decoder.JSONDecodeError: Expecting ',' delimiter: line 3 column 1 (char 42)`	char הוא ההיסט; השורה והעמודה הן מה שחשוב
Go	`invalid character '}' looking for beginning of object key string`	נותן רק את התו, ולכן צריך לחזור אחורה ולאתר אותו בעצמכם

ברגע שיש את המיקום, הדביקו את ה-JSON ל-מפענח ה-JSON המקוון; הכלי מציב את הסמן במיקום השגיאה ומדגיש את מספר השורה והעמודה — השלב הזה חוסך 90% מהסתכלות על תווים בעין.

2. שש שגיאות בתדירות גבוהה

1. פסיק עוקב

复制{
  "name": "json",
  "version": 1,
}

יש פסיק מיותר לפני }. מפרט JSON אינו מתיר פסיקים עוקבים, בעוד ש-literal של אובייקט ב-JavaScript מתיר, ולכן תצורה שהועתקה מתוך קוד היא הכי סבירה לשאת פסיק כזה. תיקון: מחקו את הפסיק האחרון; אם הנתונים האלה חיים מלכתחילה בקובץ JS, עברו להמרת JSON5 במקום לכפות אותם ל-JSON.

2. גרשיים בודדים ומפתחות ללא גרשיים

复制{ 'name': 'json' }
{ name: "json" }

מחרוזות JSON רשאיות להשתמש רק בגרשיים כפולים, וגם המפתחות חייבים להיות מחרוזות בגרשיים כפולים. שני אלה הם התחביר המוקל של JSON5 / JavaScript, לא JSON. גרש כפול בתוך מחרוזת חייב להיכתב כ-\", וקו נטוי אחורי כ-\\.

3. הערות

复制{
  // Timeout in milliseconds
  "timeout": 3000
}

לדקדוק של RFC 8259 אין מקום להערות. או מחקו את ההערות, או שמרו כ-.jsonc / .json5 והשתמשו במפענח שתומך בהערות. לשיקולי הכדאיות בין "סכמות ההערות" השונות, ראו איך לכתוב הערות ב-JSON.

4. שורות חדשות גולמיות ותווי בקרה בתוך מחרוזות

复制{"sql": "SELECT *
FROM t"}

מחרוזות JSON אינן רשאיות להכיל line feed גולמי, טאבים או תווי הבקרה U+0000–U+001F; הם חייבים להיכתב כ-\n, \t, \u0009. כשדוחפים טקסט רב-שורתי לתוך JSON, בצעו לו escape פעם אחת בעורך, או טפלו בו באופן אחיד עם מזעור ו-escape של JSON.

5. כותרת BOM

UTF-8 שנשמר על ידי Windows Notepad נושא את שלושת הבתים EF BB BF. JSON.parse מדווח Unexpected token כשהוא נתקל ב-BOM, והעין בכלל לא רואה אותו. איך לדעת: בדקו את כותרת הקובץ ב-hex, או העתיקו את התוכן לכלי מקוון וראו אם התו הראשון מוצג כ-. תיקון: שמרו כ"UTF-8 ללא BOM".

6. תוכן מקוטע

לוג שהדפיס רק את 4096 התווים הראשונים, תגובת API שנחתכה על ידי gateway, הורדה שנקטעה — הסימן המובהק של הסוג הזה הוא "השגיאה בסוף" וספירת הסוגריים לא תואמת. ספרו קודם סוגריים: אם סגירות { ו-[ לא תואמות, זה קיטוע, לא שגיאת תחביר. במקרה כזה אל תתקנו דבר — לכו להביא את הנתונים המלאים.

3. שתי אזעקות שווא בנושא טקסט סיני ו-escape

סינית הופכת ל-\u4e2d\u6587: זה escape תקין של JSON, לא טקסט משובש. אחרי הפענוח הערך חוזר לסינית; צורת ה-\u מופיעה רק כשמסתכלים ישירות על המחרוזת הגולמית. כשצריך להציג אותו לאנשים, פשוט פלטו אותו עם כלי העיצוב; צריך להתעניין באסטרטגיית escape רק כשהסינית חייבת לשרוד ב-URL או בלוג.

סינית הופכת לטקסט משובש כמו 涓枃: זו בעיית קידוד, לא בעיית JSON. זה קורה כשבתים של UTF-8 מפוענחים כ-GBK, ונוצרת התבנית הקבועה של "שלושה תווים במקום תו סיני אחד". בדקו את Content-Type: application/json; charset=utf-8 בכותרת התגובה, ובדקו אם מצוין encoding='utf-8' במפורש בעת קריאת הקובץ.

4. תהליך תיקון בחמש דקות

הדביקו בכלי: השתמשו קודם במפענח המקוון כדי לאתר את השגיאה הראשונה, ותקנו רק אחת בכל פעם;
אמתו אחרי כל תיקון: פענחו מחדש אחרי כל שינוי, כדי שתיקון של כמה מקומות בבת אחת לא יאפשר לשגיאות חדשות להסתיר את הישנה;
מזערו פעם אחת: הסירו רווחים עם מזעור ופענחו שוב; זה מבדיל בין "שגיאות מבניות" ל"בעיות רווח לבן או שורה חדשה";
השוו מבנה: אם שגיאה צצה פתאום אחרי שינוי, השתמשו בהשוואת JSON מול הגרסה הקודמת; ההבדל הוא בדרך כלל פסיק אחד;
אימות ברמת השדה: אם התחביר עובר אבל שכבת העסקים דוחה (שדה חסר, טיפוס שגוי), זה נכנס תחת אימות JSON Schema, לא בעיית תחביר.

5. למה משני קטעי JSON "זהים לכאורה" אחד נפענח והשני לא

הגורם הנפוץ ביותר הוא תווים בלתי נראים: הפסיק ברוחב מלא ，, הגרשיים ברוחב מלא “”, הרווח הבלתי-שביר U+00A0, הרווח באפס רוחב U+200B. על המסך הם כמעט בלתי ניתנים להבחנה מבני המחצית שלהם, אבל אף אחד מהם אינו חלק מדקדוק JSON.

יש רק דרך אחת לדעת: העתיקו את התוכן סביב התו הבעייתי ובדקו את ה-code points תו אחר תו. הרצת הקטע הבא בקונסולת הדפדפן מציגה כל תו שהוא non-ASCII ומחוץ לטווחים הסיניים:

复制[...text].filter((ch) => {
  const code = ch.codePointAt(0);
  return code > 127 && !(code >= 0x4e00 && code <= 0x9fff);
});

אם 0x201c (גרש כפול שמאלי), 0xff0c (פסיק ברוחב מלא) או 0x00a0 מופיעים בפלט, הם האשמים.

6. מניעה זולה מתיקון

הריצו בדיקת פענוח על קובצי תצורה לפני commit; שורה אחת ב-CI מספיקה: node -e "JSON.parse(require('fs').readFileSync('config.json','utf8'))";
ייצרו תגובות API עם ספריית סריאליזציה; לעולם אל תחברו מחרוזות ביד — מחרוזות שנבנו ביד הן המקור היחיד לפסיקים עוקבים ולגרשיים חסרים;
כשמדפיסים JSON ללוג, קראו תחילה ל-JSON.stringify במקום לשבץ אותו בתבנית, כדי שמטען חצי-כתוב לא ייחשב בטעות להודעה שלמה.

שאלות נפוצות

איך מאתרים במהירות את מיקום שגיאת התחביר ב-JSON?

קחו את ה-position או השורה/עמודה שהמפענח מדווח; position הוא היסט תו מבוסס 0, לא מספר שורה, בעוד ש-Java Jackson ו-Python מדווחים שורה ועמודה ישירות. הדביקו את ה-JSON למפענח ה-JSON המקוון והכלי מציב את הסמן במיקום השגיאה ומדגיש את השורה והעמודה. אם השגיאה יושבת בהתחלה, בדקו את כותרת הקובץ ל-BOM וחפשו תווים בלתי נראים.

למה תצורה שהועתקה מקוד כל כך נוטה לשאת פסיק עוקב?

מפרט JSON אוסר פסיקים עוקבים בעוד ש-literal של אובייקט ב-JavaScript מתיר אותם, ולכן תצורה שהועתקה מקוד JS בקלות מביאה איתם אחד. התיקון הוא פשוט למחוק את הפסיק האחרון; אם הנתונים שייכים ממילא לקובץ JS, המרת JSON5 מתאימה יותר מלכפות אותם ל-JSON.

אפשר לפענח קובץ תצורה שמכיל הערות כ-JSON רגיל?

לא — לדקדוק של RFC 8259 אין מקום להערות, ולכן פענוח ישיר מעלה שגיאה. או מחקו את ההערות, או שמרו כ-.jsonc / .json5 והשתמשו במפענח שתומך בהערות. לשיקולי הכדאיות בין סכמות הערות, ראו איך לכתוב הערות ב-JSON.