此页面由 Cloud Translation API 翻译。

Chrome 开发者工具中的自动 Workspace 连接

Workspace 是一项强大的功能，可让您直接在 Chrome DevTools 中修改网站的源文件，无需在代码编辑器和浏览器之间不断切换。

概览

Chrome 开发者工具中的 Workspace 可将 Web 服务器提供的文件映射到您计算机上本地文件夹中的文件。为本地项目启用工作区后，您在开发者工具的 Sources 面板中所做的任何文件更改都会自动保存到本地项目文件中。这样一来，您就可以获得顺畅的编辑体验，感觉就像直接在项目的代码库中工作一样，同时还能受益于开发者工具的实时分析。

自动连接工作区的优势

自动工作区连接功能可省去手动配置，从而简化工作区设置。本地开发服务器可以提供 Chrome 开发者工具自动检测到的特殊 devtools.json 文件，而无需手动将项目文件夹添加到开发者工具。这有以下几点好处：

更快速的调试：在开发者工具中编辑文件，无需离开浏览器或手动保存，即可立即看到更新。
实时更改：更改会立即反映在本地文件和浏览器中，从而提高开发速度。
无需手动设置：自动映射项目文件，缩短设置时间，尤其是在新项目或团队成员加入时。

自动工作区连接功能是如何运作的？

自动工作区连接的原理是让本地开发服务器在预定义的路径中公开特定的 JSON 文件。当 Chrome DevTools 处于打开状态，并且您正在浏览从 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 v4)。这有助于开发者工具区分不同的项目。

DevTools 接收并处理此文件后，会在来源 > 工作区面板中提供一个连接按钮。

专为本地开发和调试而设计

通过 devtools.json 实现的自动工作区发现机制专为本地开发环境设计，仅在应用通过 localhost 提供服务时有效。Chrome 开发者工具仅在您调试本地项目时，以开发模式发送 /.well-known/appspecific/com.chrome.devtools.json 请求。此功能不适用于生产环境。

授予访问本地文件的权限

出于安全考虑，Chrome 要求网站获得明确的用户许可才能访问本地网络或计算机上的文件。当开发者工具尝试使用 devtools.json 连接到本地项目时，系统会提示您授予 Chrome 访问项目目录的权限。此权限请求遵循 Chrome 的本地网络访问权限政策，该政策限制从公共网络向本地目标发送请求，除非已授予权限。只有在安全情境 (HTTPS) 中才能请求此权限。对于本地开发，这通常意味着 localhost 被视为安全情境。

创建并提供 `devtools.json` 文件

对于在本地开发服务器上运行的典型前端项目，您需要配置服务器以使用正确的 JSON 内容响应 /.well-known/appspecific/com.chrome.devtools.json 请求。

您通常可以按以下方式着手解决此问题：

生成 UUID：您需要一个 UUID v4。您可以使用在线工具或脚本生成一个。
确定项目根目录：获取项目根目录的绝对路径。
创建端点：配置开发服务器以处理对 /.well-known/appspecific/com.chrome.devtools.json 的 GET 请求。
提供 JSON：当此端点被命中时，提供带有 Content-Type: application/json 标头和 devtools.json 内容的 JSON 响应。

devtools.json 文件中指定的 workspace.root 路径必须是本地文件系统上项目根目录的绝对路径。这意味着路径会因您的操作系统（例如，macOS 或 Linux 上的 /Users/yourname/projects/my-app 或 Windows 上的 C:\Users\yourname\projects\my-app）和具体项目设置而异。请考虑将其添加到忽略的文件中（例如添加到 .gitignore 列表），以避免在生产环境中签入此文件。

请务必确保您的服务器动态生成或提供此路径，或者您已针对开发环境正确配置此路径。请考虑将其添加到忽略的文件中（例如添加到 .gitignore 列表中），以避免在生产环境中签入此文件。

示例

您可以根据项目的技术堆栈，通过多种方式提供 devtools.json 文件。

Node.js 和 Express

此脚本运行的是一个最小的 Express 服务器。它会在 /.well-known/appspecific/com.chrome.devtools.json 处提供一个 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 错误

如果您不想为特定项目使用此功能，并且在服务器日志中看到 /.well-known/appspecific/com.chrome.devtools.json 请求的 404 错误，则可以忽略这些错误。如果未提供相应文件，则该请求不会造成任何危害。或者，您也可以将服务器配置为针对此特定路径返回 404 状态，而不记录错误。

如何在 Chrome 开发者工具中停用此功能

如果您需要停用 Chrome 开发者工具中的自动工作区发现功能，则需要设置相应的 Chrome flag：

打开 Chrome，然后前往 chrome://flags。
搜索“DevTools Project Settings”，并将其设置为 Disabled。
您可能还会找到一个名为“DevTools Automatic Workspace Folders”的相关标志，也可以将其停用。
重新启动 Chrome 以使更改生效。

摘要

通过了解和利用 devtools.json 机制，您可以显著提升 Chrome 开发者工具的本地开发工作流程。