اتصال خودکار فضای کاری در Chrome DevTools

Ewa Gasperowicz
X

فضای کاری یک ویژگی قدرتمند است که به شما امکان می‌دهد مستقیماً فایل‌های منبع وب‌سایت خود را از داخل Chrome DevTools ویرایش کنید و نیاز به جابجایی مداوم بین ویرایشگر کد و مرورگر را از بین ببرید.

نمای کلی

یک فضای کاری در DevTools کروم، فایل‌هایی را که توسط یک وب سرور ارائه می‌شوند، به فایل‌هایی در یک پوشه محلی در رایانه شما نگاشت می‌کند. وقتی یک فضای کاری را برای یک پروژه محلی فعال می‌کنید، هر تغییری که در فایل‌های موجود در پنل منابع DevTools ایجاد کنید، به طور خودکار در فایل‌های پروژه محلی شما ذخیره می‌شود. این یک تجربه ویرایش یکپارچه را فراهم می‌کند و باعث می‌شود احساس کنید که مستقیماً روی کدبیس پروژه خود کار می‌کنید و در عین حال از بینش‌های بلادرنگ DevTools بهره‌مند می‌شوید.

مزایای اتصال خودکار فضای کاری

اتصال خودکار فضای کاری با حذف پیکربندی دستی، تنظیمات فضای کاری را بهبود می‌بخشد. به جای اضافه کردن دستی پوشه‌های پروژه به DevTools، سرور توسعه محلی شما می‌تواند یک فایل devtools.json ویژه ارائه دهد که Chrome DevTools به طور خودکار آن را تشخیص می‌دهد. این امر مزایای متعددی دارد:

  • اشکال‌زدایی سریع‌تر: فایل‌ها را در DevTools ویرایش کنید و به‌روزرسانی‌ها را فوراً و بدون ترک مرورگر یا ذخیره دستی مشاهده کنید.
  • تغییرات در لحظه: تغییرات بلافاصله در فایل‌های محلی و مرورگر شما منعکس می‌شوند و سرعت توسعه را بهبود می‌بخشند.
  • بدون نیاز به تنظیمات دستی: نگاشت فایل‌های پروژه را خودکار می‌کند و زمان راه‌اندازی را، به خصوص برای پروژه‌های جدید یا هنگام ورود اعضای تیم به سیستم، کاهش می‌دهد.

اتصال خودکار فضای کاری چگونه کار می‌کند؟

اتصال خودکار به فضای کاری با قرار دادن یک فایل JSON خاص در مسیر از پیش تعریف شده توسط سرور توسعه محلی شما کار می‌کند. وقتی Chrome DevTools باز است و شما در حال پیمایش یک وب‌سایت ارائه شده از localhost هستید، به طور خودکار درخواستی را به آدرس زیر ارسال می‌کند:

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

اگر سرور شما با یک فایل devtools.json معتبر پاسخ دهد، DevTools از اطلاعات درون آن برای اتصال خودکار به پوشه‌های منبع پروژه شما استفاده می‌کند. فایل devtools.json معمولاً شامل موارد زیر است:

{
  "workspace": {
    "root": "/Users/yourname/path/to/your/project",
    "uuid": "a-random-version-4-uuid"
  }
}
  • workspace.root : مسیر مطلق به دایرکتوری ریشه پروژه شما در سیستم فایل محلی شما.
  • workspace.uuid : یک شناسه منحصر به فرد (UUID نسخه ۴) برای پروژه شما. این به DevTools کمک می‌کند تا پروژه‌های مختلف را از هم تشخیص دهد.

وقتی DevTools این فایل را دریافت و پردازش کرد، دکمه‌ی Connect را در پنل Sources > Workspaces ارائه می‌دهد.

طراحی شده برای توسعه محلی و اشکال زدایی

مکانیزم کشف خودکار فضای کاری از طریق devtools.json منحصراً برای محیط‌های توسعه محلی طراحی شده است و فقط زمانی کار می‌کند که برنامه شما از localhost ارائه شود. Chrome DevTools درخواست /.well-known/appspecific/com.chrome.devtools.json را فقط در حالت توسعه و زمانی که در حال اشکال‌زدایی یک پروژه محلی هستید، ارسال می‌کند. این ویژگی برای محیط‌های عملیاتی در نظر گرفته نشده است.

اعطای مجوز دسترسی به فایل‌های محلی

به دلایل امنیتی، کروم برای دسترسی یک وب‌سایت به فایل‌های موجود در شبکه محلی یا دستگاه شما، به اجازه صریح کاربر نیاز دارد. هنگامی که DevTools سعی می‌کند با استفاده از devtools.json به پروژه محلی شما متصل شود، از شما خواسته می‌شود که به کروم اجازه دسترسی به دایرکتوری پروژه خود را بدهید. این درخواست مجوز با سیاست‌های دسترسی به شبکه محلی کروم مطابقت دارد، که درخواست‌ها از شبکه‌های عمومی را به مقاصد محلی محدود می‌کند، مگر اینکه اجازه داده شود. امکان درخواست این مجوز محدود به زمینه‌های امن (HTTPS) است. برای توسعه محلی، این معمولاً به این معنی است که localhost به عنوان یک زمینه امن در نظر گرفته می‌شود.

یک فایل devtools.json ایجاد و ارائه کنید

برای یک پروژه frontend معمولی که روی یک سرور توسعه محلی اجرا می‌شود، باید سرور خود را طوری پیکربندی کنید که به درخواست /.well-known/appspecific/com.chrome.devtools.json با محتوای JSON صحیح پاسخ دهد.

در اینجا نحوه برخورد کلی با این موضوع آورده شده است:

  1. ایجاد UUID: شما به یک UUID نسخه ۴ نیاز دارید. می‌توانید با استفاده از ابزارهای آنلاین یا یک اسکریپت، یکی ایجاد کنید.
  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 و اکسپرس

این اسکریپت یک سرور اکسپرس مینیمال را اجرا می‌کند. این اسکریپت یک فایل 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 به صفحه اصلی پروژه مراجعه کنید.

ادغام‌ها

برخی از فریم‌ورک‌های frontend و ابزارهای ساخت، افزونه‌ها یا پیکربندی‌هایی را برای ساده‌سازی این فرآیند ارائه می‌دهند.

ویت

برای پروژه‌های مبتنی بر 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',
    }),
  ],
});

زاویه دار

اگر از 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 تولید شده را مشاهده کنید.

عیب‌یابی

شما می‌توانید مشکلات معمول مربوط به اتصال خودکار فضای کاری را با دنبال کردن نکات این بخش حل کنید.

حذف یک پوشه از Workspaces

اگر پوشه‌ی پروژه‌ای از قبل به طور خودکار متصل شده است، می‌توانید آن را به صورت دستی از تنظیمات فضای کاری DevTools خود حذف کنید:

  • ابزارهای توسعه کروم را باز کنید.
  • به برگه منابع بروید.
  • در پنل سمت چپ، زیرشاخه‌ی Workspaces را انتخاب کنید.
  • روی پوشه پروژه ناخواسته کلیک راست کرده و گزینه Remove from Workspace را انتخاب کنید.

نادیده گرفتن خطاهای ۴۰۴ در سرور

اگر نمی‌خواهید از این ویژگی برای یک پروژه خاص استفاده کنید و در گزارش‌های سرور خود، خطاهای ۴۰۴ را برای درخواست /.well-known/appspecific/com.chrome.devtools.json مشاهده می‌کنید، می‌توانید این خطاها را نادیده بگیرید. اگر فایل ارائه نشود، درخواست بی‌ضرر است. از طرف دیگر، می‌توانید سرور خود را طوری پیکربندی کنید که بدون ثبت خطا، با وضعیت ۴۰۴ برای این مسیر خاص پاسخ دهد.

نحوه غیرفعال کردن این ویژگی در Chrome DevTools

اگر نیاز دارید که ویژگی کشف خودکار فضای کاری را در Chrome DevTools غیرفعال کنید، باید پرچم کروم مناسب را تنظیم کنید:

  • کروم را باز کنید و به chrome://flags بروید.
  • عبارت « DevTools Project Settings » را جستجو کنید و آن را روی «Disabled» تنظیم کنید.
  • همچنین ممکن است یک پرچم مرتبط با نام « پوشه‌های خودکار فضای کاری DevTools » پیدا کنید و می‌توانید آن را نیز غیرفعال کنید.
  • برای اعمال تغییرات، کروم را مجدداً اجرا کنید.

خلاصه

با درک و استفاده از مکانیزم devtools.json ، می‌توانید گردش کار توسعه محلی خود را با Chrome DevTools به طور قابل توجهی بهبود بخشید.