ما هو ملف JSON، وبماذا تفتحه، وكيف تحرره

الخلاصة: قبل فتح ملف JSON تأكد من ترميزه وBOM، ثم تحقق من أن البنية لا تكون إلا كائنًا أو مصفوفة؛ وبعد التحرير تحقق منه دائمًا بمحلل لا بالعين المجردة على الأقواس والفواصل.

إنه ببساطة ملف نصي عادي بامتداد .json، وحتى Notepad يستطيع فتحه. الصداع الحقيقي ليس "أنه لا يُفتح"، بل أنك بعد فتحه لا ترى ما كسرته.

1. ما الذي يوجد فعليًا داخل ملف JSON

لا يمكن أن يحتوي ملف JSON صالح إلا على أحد شيئين: كائن {...} أو مصفوفة [...]. ولا شيء غير ذلك — لا تصريحات متغيرات، ولا تعليقات، ولا دوال.

复制{
  "name": "order service",
  "port": 8080,
  "debug": false,
  "upstream": ["10.0.0.11", "10.0.0.12"],
  "timeout": null
}

يكفي التعرف على ثلاثة أمور بنيويًا:

امتداد الملف لا يحدد المحتوى: package.json وtsconfig.json وcomposer.json كلها من النوع نفسه؛ لكن أدوات مختلفة وافقت ببساطة على قراءة مفاتيح مختلفة منها.

2. ثلاث طرق لفتحه، تختارها حسب الحالة

نظرة سريعة فقط: افتحه في المتصفح. اسحب الملف إلى نافذة Chrome أو Edge فيعرضه المتصفح كما هو؛ وإن كان امتداد JSON Viewer مثبتًا فسيُنسَّق تلقائيًا ويصبح قابلًا للطي.

تحتاج إلى تحرير المحتوى: استخدم محررًا. VS Code وSublime وNotepad++ كلها توفر تلوين صياغة JSON ومطابقة الأقواس، وShift + Alt + F في VS Code ينسّق المستند. لاحظ أن Windows Notepad قد يضيف BOM عند الحفظ، فقد لا تسري تغييرات إعداداتك؛ والأفضل تجنبه.

لا تريد تثبيت أي شيء، وتريد التحقق فقط: استخدم منسّق JSON. الصق المحتوى فترى فورًا أرقام الأسطر والأعمدة ومواضع الخطأ وشجرة قابلة للطي؛ ثم انسخ الناتج عند الانتهاء. تُعالَج البيانات محليًا في المتصفح ولا تُرفع إلى خادم.

الملفات الكبيرة (عشرات MB فأكثر): لا تفرض فتحها في محرر. فتح ملف JSON بحجم 100 MB في VS Code سيتجمد حتى تشك في خيارات حياتك؛ استخدم سطر الأوامر لفحص البنية أولًا:

复制# Look at the first 20 lines to confirm whether it is an array
head -n 20 data.json

# Use jq to list top-level keys without loading the whole file
jq -r 'keys[]' data.json | head

# Count the array length
jq 'length' data.json

3. ماذا تفعل عندما يُفتح بالنقر المزدوج فيظهر نص مشوّه

ثلاثة أسباب، ولكل منها معالجة مختلفة:

1. إنه في الواقع ملف ثنائي (مثل أرشيف مضغوط، أو ملف قاعدة بيانات مُصدَّر، بامتداد .json). استخدم file data.json لرؤية النوع الحقيقي؛ ولا تفرض معاملته كنص.
2. الترميز ليس UTF-8. النص الصيني المُرمَّز بـ GBK يظهر مشوّهًا في بيئة UTF-8. استخدم "Reopen with encoding" في المحرر لتجربة GBK مرة؛ فإن ظهر صحيحًا فاحفظه بترميز UTF-8.
3. الملف مشفَّر أو مضغوط. العَرَض هو PK (zip) أو كومة من علامات الاستفهام في البداية؛ وهذه الملفات يجب فك ضغطها أو فك تشفيرها أولًا.

4. كيف تؤكد أن شيئًا لم ينكسر بعد التحرير

JSON بلا تسامح: فاصلة ناقصة أو فاصلة زائدة أو علامة اقتباس ناقصة، والملف كله ميت، وكثيرًا ما يشير موضع الخطأ المُبلَّغ عنه إلى السطر التالي. لذا يجب أن تتحقق بعد التحرير؛ ولا تعتمد على عينيك.

إجراءات التحرير الثلاثة عالية الخطر، مرتبة حسب تكرار إحداثها للمشكلات:

التحقق بسيط: الصق المحتوى في المدقق على الإنترنت وابحث عن نص أحمر، أو نفّذ سطرًا واحدًا في سطر الأوامر:

复制python3 -m json.tool config.json > /dev/null && echo OK

إن طبع OK فالملف صالح. وإن أردت التحقق من أنواع الحقول أيضًا (مثلًا port يجب أن يكون عددًا وname يجب ألا يكون فارغًا)، فإن كتابة JSON Schema أكثر موثوقية بكثير من العين البشرية.

5. كيف يختلف .json عن أقاربه المقربين

لا تتفاجأ برؤية تعليقات في tsconfig.json؛ فهو في الواقع يُعالَج بوصفه .jsonc. وأعطِ المحتوى نفسه إلى JSON.parse وسيثير خطأً. وعندما تحتاج إلى التحويل بينها، استخدم JSON5 إلى JSON لنزع التعليقات والفواصل الزائدة بنقرة واحدة.

6. عندما يحين وقت تبديل صيغة التخزين

يناسب JSON الحالات التي يكون فيها "البنية غير ثابتة، ويحتاج البشر إلى قراءتها، وتنتقل بين اللغات". فإن تجاوز الملف عشرات MB وكانت بنية الحقول مستقرة واحتجت إلى استعلامات شرطية، فالبقاء على JSON مجرد تعقيد لنفسك — انتقل إلى SQLite أو Parquet، أو حمّله إلى قاعدة بيانات؛ فأداء القراءة/الكتابة يختلف بمقدار رتب متعددة. وللمقارنات الدقيقة راجع تحليل JSON الكبير وتدفقه.

FAQ

كيف أفحص ملف JSON أكبر من أن يُفتح؟

لا تفرض فتحه في محرر؛ ففتح ملف JSON بحجم 100 MB في VS Code سيتجمد حتى تشك في خيارات حياتك. استخدم سطر الأوامر لفحص البنية أولًا: head -n 20 يؤكد ما إذا كان مصفوفة، وjq -r 'keys[]' يسرد مفاتيح المستوى الأعلى فقط، وjq 'length' يحسب طول المصفوفة. ولا يقوم أي من هذه الأوامر بتحميل الملف كله.

لماذا تمنع تعديلاتي في Notepad الإعدادات من السريان؟

قد يضيف Windows Notepad BOM عند الحفظ، والملف الذي يحمل BOM يفشل في تحليل الإعدادات، فلا يسري المحتوى المحرر أبدًا. وتوصية المقال استخدام محررات مثل VS Code أو Sublime أو Notepad++، التي توفر تلوين صياغة JSON ومطابقة الأقواس. وإن كنت قد استخدمت Notepad بالفعل، فاحفظ مرة أخرى بصيغة "UTF-8 without BOM" وأعد المحاولة.

هل أستطيع معاملة ملف JSON بوصفه JSON5 وإضافة تعليقات؟

لا — لا يسمح المحلل القياسي بالتعليقات في ملف .json ويثير JSON.parse خطأً فورًا. التعليقات تنتمي إلى ملفات .jsonc أو .json5 التي يقرأها المحلل المطابق. وملفات مثل tsconfig.json تُعالَج فعليًا بوصفها .jsonc؛ وأعطِ المحتوى نفسه إلى JSON.parse وسيفشل.