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

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

نمای کلی

یک فضای کاری در Chrome DevTools فایل‌های ارائه‌شده توسط وب سرور را به فایل‌های موجود در یک پوشه محلی در رایانه شما نگاشت می‌کند. هنگامی که یک فضای کاری را برای یک پروژه محلی فعال می کنید، هر تغییری که در فایل های پنل DevTools' Sources ایجاد می کنید به طور خودکار در فایل های پروژه محلی شما ذخیره می شود. این یک تجربه ویرایش یکپارچه را فراهم می کند، و این احساس را ایجاد می کند که به طور مستقیم بر روی پایگاه کد پروژه خود کار می کنید و در عین حال از بینش بلادرنگ 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 v4) برای پروژه شما. این به DevTools کمک می کند تا بین پروژه های مختلف تمایز قائل شود.

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

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

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

اجازه دسترسی به فایل های محلی را بدهید

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

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

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

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

1. یک UUID ایجاد کنید: به UUID v4 نیاز دارید. می توانید با استفاده از ابزارهای آنلاین یا یک اسکریپت یکی را ایجاد کنید.
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 در ویندوز) و راه اندازی پروژه خاص شما متفاوت خواهد بود. برای جلوگیری از بررسی این فایل برای محیط تولید، آن را به فایل های نادیده گرفته شده خود اضافه کنید (به عنوان مثال به لیست 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 (از جمله 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 خود حذف کنید:

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

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

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

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

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

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

خلاصه

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