الاتصال التلقائي بمساحة العمل في Chrome DevTools

ميزة "مساحة العمل" هي ميزة فعّالة تتيح لك تعديل ملفات المصدر لموقعك الإلكتروني مباشرةً من داخل "أدوات مطوّري البرامج في Chrome"، ما يغنيك عن الحاجة إلى التبديل باستمرار بين أداة تعديل الرموز البرمجية والمتصفّح.

نظرة عامة

تتيح لك مساحة العمل في "أدوات مطوّري البرامج في Chrome" ربط الملفات التي يعرضها خادم الويب بالملفات الموجودة في مجلد محلي على جهاز الكمبيوتر. عند تفعيل مساحة عمل لمشروع محلي، يتم تلقائيًا حفظ أي تغييرات تجريها على الملفات في لوحة المصادر في "أدوات مطوّلي البرامج" في ملفات مشروعك المحلي. يوفّر ذلك تجربة تعديل سلسة، ما يجعلك تشعر وكأنّك تعمل مباشرةً على قاعدة الرموز البرمجية لمشروعك مع الاستفادة من الإحصاءات في الوقت الفعلي التي تقدّمها "أدوات مطوّلي البرامج".

مزايا الربط التلقائي بمساحة العمل

تعمل ميزة الربط التلقائي بمساحة العمل على تحسين عملية إعداد مساحة العمل من خلال إلغاء الإعداد اليدوي. بدلاً من إضافة مجلدات المشاريع يدويًا إلى DevTools، يمكن لخادم التطوير المحلي توفير ملف devtools.json خاص ترصده "أدوات مطوّري البرامج في Chrome" تلقائيًا. ويوفّر ذلك عدة مزايا:

• تصحيح الأخطاء بشكل أسرع: عدِّل الملفات في "أدوات المطوّرين" واطّلِع على التعديلات على الفور بدون مغادرة المتصفّح أو الحفظ يدويًا.
• التغييرات في الوقت الفعلي: تنعكس التغييرات فورًا في ملفاتك المحلية والمتصفح، ما يؤدي إلى تحسين سرعة التطوير.
• عدم الحاجة إلى إعداد يدوي: تعمل هذه الميزة على أتمتة ربط ملفات المشاريع، ما يقلّل من وقت الإعداد، خاصةً للمشاريع الجديدة أو عند إعداد أعضاء الفريق.

كيف تعمل ميزة الربط التلقائي بمساحة العمل؟

تعمل ميزة الربط التلقائي بمساحة العمل من خلال جعل خادم التطوير المحلي يعرض ملف JSON معيّنًا في مسار محدّد مسبقًا. عندما تكون "أدوات مطوّري البرامج في Chrome" مفتوحة وتتصفّح موقعًا إلكترونيًا يتم عرضه من localhost، يتم تلقائيًا إرسال طلب إلى:

/.well-known/appspecific/com.chrome.devtools.json

إذا ردّ الخادم بملف devtools.json صالح، تستخدم "أدوات مطوّلي البرامج" المعلومات الواردة فيه للاتصال تلقائيًا بمجلدات المصدر الخاصة بمشروعك. يحتوي ملف devtools.json عادةً على ما يلي:

{
  "workspace": {
    "root": "/Users/yourname/path/to/your/project",
    "uuid": "a-random-version-4-uuid"
  }
}

• workspace.root: المسار المطلق إلى الدليل الجذر لمشروعك في نظام الملفات المحلي
• workspace.uuid: معرّف فريد (UUID الإصدار 4) لمشروعك. يساعد ذلك "أدوات مطوّلي البرامج" في التمييز بين المشاريع المختلفة.

بعد أن تتلقّى "أدوات مطوّري البرامج" هذا الملف وتعالجه، ستوفّر زر ربط في اللوحة المصادر > مساحات العمل.

مصمَّم للتطوير وتصحيح الأخطاء على الجهاز

تم تصميم آلية البحث التلقائي عن مساحة العمل من خلال devtools.json حصريًا لبيئات التطوير المحلية، ولا تعمل إلا عندما يتم عرض تطبيقك من localhost. ترسل "أدوات مطوّري البرامج في Chrome" طلب /.well-known/appspecific/com.chrome.devtools.json في وضع التطوير فقط عند تصحيح أخطاء مشروع محلي. هذه الميزة غير مخصَّصة لبيئات الإنتاج.

منح الإذن بالوصول إلى الملفات المحلية

لأسباب تتعلق بالأمان، يطلب Chrome من المستخدم منح إذن صريح للموقع الإلكتروني للوصول إلى الملفات على شبكتك المحلية أو جهازك. عندما تحاول "أدوات مطوّري البرامج" الاتصال بمشروعك المحلي باستخدام devtools.json، سيُطلب منك منح Chrome الإذن بالوصول إلى دليل مشروعك. يتوافق طلب الإذن هذا مع سياسات الوصول إلى الشبكة المحلية في Chrome التي تقيّد الطلبات من الشبكات العامة إلى الوجهات المحلية ما لم يتم منح الإذن. تقتصر إمكانية طلب هذا الإذن على السياقات الآمنة (HTTPS). بالنسبة إلى التطوير المحلي، يعني هذا عادةً أنّ localhost يتم التعامل معه على أنّه سياق آمن.

إنشاء ملف devtools.json وعرضه

بالنسبة إلى مشروع نموذجي للواجهة الأمامية يعمل على خادم تطوير محلي، عليك ضبط الخادم للاستجابة لطلب /.well-known/appspecific/com.chrome.devtools.json بالمحتوى الصحيح بتنسيق JSON.

في ما يلي كيفية التعامل مع هذه المشكلة بشكل عام:

1. إنشاء معرّف فريد عالمي (UUID): يجب استخدام معرّف فريد عالمي الإصدار 4. يمكنك إنشاء رمز باستخدام أدوات على الإنترنت أو نص برمجي.
2. تحديد جذر المشروع: احصل على المسار المطلق للدليل الجذر لمشروعك.
3. إنشاء نقطة نهاية: اضبط خادم التطوير للتعامل مع طلبات GET إلى /.well-known/appspecific/com.chrome.devtools.json.
4. عرض JSON: عند الوصول إلى نقطة النهاية هذه، اعرض استجابة JSON مع العنوان Content-Type: application/json والمحتوى devtools.json.

يجب أن يكون مسار workspace.root المحدّد في ملف devtools.json مسارًا مطلقًا إلى الدليل الجذر لمشروعك في نظام الملفات المحلي. وهذا يعني أنّ المسار سيختلف حسب نظام التشغيل (على سبيل المثال، /Users/yourname/projects/my-app على نظام التشغيل macOS أو Linux أو C:\Users\yourname\projects\my-app على نظام التشغيل Windows) وإعداد مشروعك المحدّد. ننصحك بإضافته إلى الملفات التي يتم تجاهلها (مثل قائمة .gitignore) لتجنُّب تسجيل الدخول إلى هذا الملف في بيئة الإنتاج.

من المهم أن ينشئ الخادم هذا المسار أو يعرضه بشكلٍ ديناميكي أو أن تضبطه بشكلٍ صحيح لبيئة التطوير. ننصحك بإضافته إلى الملفات التي تم تجاهلها (على سبيل المثال، إلى قائمة .gitignore) لتجنُّب تسجيل الدخول إلى هذا الملف في بيئة الإنتاج.

أمثلة

تتوفّر طرق عديدة يمكنك من خلالها تقديم ملف devtools.json، وذلك حسب مجموعة التكنولوجيات التي يستخدمها مشروعك.

Node.js وExpress

يشغّل هذا النص البرمجي خادم Express بسيطًا. يعرض ملف JSON في /.well-known/appspecific/com.chrome.devtools.json يحتوي على المسار إلى projectRoot.، ويشير إلى المجلد الذي يتم تشغيل الخادم منه. عدِّل المتغيّر projectRoot ليشير بشكل صحيح إلى الدليل الجذر الفعلي لمشروعك، وليس بالضرورة إلى المكان الذي يوجد فيه نص الخادم البرمجي.

const express = require('express');
const path = require('path');
const { v4: uuidv4 } = require('uuid');

const app = express();
const port = 3000;

if (process.env.NODE_ENV !== 'production') {
  app.get('/.well-known/appspecific/com.chrome.devtools.json', (req, res) => {
    const projectRoot = path.resolve(__dirname);
    const workspaceUuid = uuidv4();

    res.json({
      workspace: {
        root: projectRoot,
        uuid: workspaceUuid,
      },
    });
  });
}

app.listen(port, () => {
  console.log(`Development server listening at http://localhost:${port}`);
});

استخدام النص البرمجي devtools-json-generator

يمكنك استخدام generate-devtools-json لإنشاء devtools.json نيابةً عنك.

لإنشاء ملف devtools.json في الدليل الحالي، نفِّذ ما يلي:

npx generate-devtools-json

أو لإنشاء الملف في دليل معيّن، مرِّر الدليل كوسيطة:

npx generate-devtools-json /path/to/your/project

يمكنك الاطّلاع على مزيد من المعلومات حول devtools-json-generator في الصفحة الرئيسية للمشروع.

عمليات التكامل

توفّر بعض أُطر العمل وأدوات الإنشاء للواجهة الأمامية مكوّنات إضافية أو إعدادات لتبسيط هذه العملية.

Vite

بالنسبة إلى المشاريع المستندة إلى Vite (بما في ذلك SvelteKit)، فإنّ vite-plugin-devtools-json هو الحلّ. تعمل هذه الأداة على أتمتة عملية إنشاء ملف devtools.json وعرضه بشكل فوري.

لاستخدامها، ثبِّت المكوّن الإضافي باتّباع الخطوات التالية:

npm install -D vite-plugin-devtools-json

بعد ذلك، أضِفها إلى vite.config.js (أو vite.config.ts):

// vite.config.js
import { defineConfig } from 'vite';
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({
      // Optional: specify a custom root path if different from Vite's root
      // root: '/path/to/your/project/root',
    }),
  ],
});

Angular

إذا كنت تستخدم ng serve لتشغيل مشروع Angular محليًا (وكان إصدار @angular/cli لديك هو 19.0.0 أو إصدارًا أحدث)، يوفّر Angular CLI برامج وسيطة تعرض ملف devtools.json الصحيح تلقائيًا.

على سبيل المثال، لإنشاء تطبيق جديد وتشغيله:

npm install -g @angular/cli
ng new my-first-angular-app
ng serve

عند الانتقال إلى https://localhost:4200/.well-known/appspecific/com.chrome.devtools.json، يمكنك الاطّلاع على ملف JSON الذي تم إنشاؤه.

تحديد المشاكل وحلّها

يمكنك حلّ المشاكل النموذجية المتعلّقة بالربط التلقائي لمساحة العمل باتّباع النصائح الواردة في هذا القسم.

إزالة مجلد من "مساحات العمل"

إذا تم ربط مجلد مشروع تلقائيًا، يمكنك إزالته يدويًا من إعدادات مساحة عمل "أدوات مطوّري البرامج" باتّباع الخطوات التالية:

• افتح أدوات مطوّري البرامج في Chrome.
• انتقِل إلى علامة التبويب المصادر.
• في اللوحة اليمنى، انقر على علامة التبويب الفرعية مساحات العمل.
• انقر بزر الماوس الأيمن على مجلد المشروع غير المرغوب فيه واختَر إزالة من مساحة العمل.

تجاهل أخطاء 404 على الخادم

إذا كنت لا تريد استخدام هذه الميزة لمشروع معيّن وظهرت لك أخطاء 404 للطلب /.well-known/appspecific/com.chrome.devtools.json في سجلات الخادم، يمكنك تجاهل هذه الأخطاء. الطلب غير ضار إذا لم يتم عرض الملف. بدلاً من ذلك، يمكنك ضبط إعدادات الخادم لعرض حالة 404 لهذا المسار المحدّد بدون تسجيل خطأ.

كيفية إيقاف هذه الميزة في Chrome DevTools

إذا كنت بحاجة إلى إيقاف ميزة "الرصد التلقائي لمساحات العمل" في "أدوات مطوّري البرامج في Chrome"، عليك ضبط علامة Chrome المناسبة:

• افتح Chrome وانتقِل إلى chrome://flags.
• ابحث عن "إعدادات مشروع أدوات مطوّري البرامج" واضبطها على غير مفعّلة.
• قد تجد أيضًا علامة ذات صلة باسم "مجلدات مساحة العمل التلقائية في أدوات مطوّلي البرامج" ويمكنك إيقافها أيضًا.
• أعِد تشغيل Chrome لتصبح التغييرات سارية المفعول.

ملخّص

من خلال فهم آلية devtools.json واستخدامها، يمكنك تحسين سير عمل التطوير المحلي بشكل كبير باستخدام "أدوات مطوّري البرامج في Chrome".