Эта страница переведена с помощью Cloud Translation API.

Автоматическое подключение к рабочей области в Chrome DevTools

Workspace — это мощная функция, которая позволяет вам редактировать исходные файлы вашего веб-сайта напрямую из Chrome DevTools, устраняя необходимость постоянно переключаться между редактором кода и браузером.

Обзор

Рабочее пространство в Chrome 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 v4) вашего проекта. Он помогает DevTools различать разные проекты.

После того как DevTools получит и обработает этот файл, на панели Источники > Рабочие области появится кнопка Подключиться .

Разработано для локальной разработки и отладки

Механизм автоматического обнаружения рабочей области через devtools.json разработан исключительно для локальных сред разработки и работает только при работе приложения с localhost . Chrome DevTools отправляет запрос /.well-known/appspecific/com.chrome.devtools.json только в режиме разработки при отладке локального проекта. Эта функция не предназначена для производственных сред.

Предоставить разрешение на доступ к локальным файлам

В целях безопасности Chrome требует явного разрешения пользователя для доступа веб-сайта к файлам в вашей локальной сети или на вашем компьютере. При попытке DevTools подключиться к вашему локальному проекту с помощью devtools.json вам будет предложено предоставить Chrome разрешение на доступ к каталогу вашего проекта. Этот запрос разрешения соответствует политикам доступа к локальной сети Chrome , которые ограничивают запросы из общедоступных сетей к локальным адресам без соответствующего разрешения. Возможность запроса этого разрешения ограничена безопасными контекстами (HTTPS). При локальной разработке это обычно означает, что localhost рассматривается как безопасный контекст.

Создайте и используйте файл `devtools.json`

Для типичного проекта frontend, работающего на локальном сервере разработки, вам необходимо настроить сервер так, чтобы он отвечал на запрос /.well-known/appspecific/com.chrome.devtools.json правильным содержимым JSON.

Вот как можно подойти к этому вопросу:

Сгенерируйте UUID: вам понадобится UUID версии 4. Вы можете сгенерировать его с помощью онлайн-инструментов или скрипта.
Определите корень проекта: получите абсолютный путь к корневому каталогу вашего проекта.
Создайте конечную точку: настройте сервер разработки для обработки GET-запросов к /.well-known/appspecific/com.chrome.devtools.json .
Предоставление 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 (включая 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 .
Перейдите на вкладку Источники .
На левой панели выберите вкладку Рабочие области .
Щелкните правой кнопкой мыши по ненужной папке проекта и выберите Удалить из рабочей области .

Игнорировать ошибки 404 на сервере

Если вы не хотите использовать эту функцию для конкретного проекта и видите ошибки 404 для запроса /.well-known/appspecific/com.chrome.devtools.json в журналах сервера, вы можете игнорировать эти ошибки. Запрос безвреден, если файл не будет доставлен. Кроме того, вы можете настроить сервер так, чтобы он возвращал код 404 для этого конкретного пути без регистрации ошибки.

Как отключить эту функцию в Chrome DevTools

Если вам необходимо отключить функцию автоматического обнаружения рабочего пространства в Chrome DevTools, вам необходимо установить соответствующий флаг Chrome :

Откройте Chrome и перейдите по адресу chrome://flags .
Найдите « Настройки проекта DevTools » и установите для него значение «Отключено» .
Вы также можете найти связанный флаг под названием « DevTools Automatic Workspace Folders » и также можете его отключить.
Перезапустите Chrome, чтобы изменения вступили в силу.

Краткое содержание

Понимая и используя механизм devtools.json , вы можете значительно улучшить локальный процесс разработки с помощью Chrome DevTools.