本頁面由 Cloud Translation API 翻譯而成。

在 Chrome 開發人員工具中自動連線至 Workspace

Workspace 是強大的功能，可讓您直接在 Chrome 開發人員工具中編輯網站的來源檔案，不必在程式碼編輯器和瀏覽器之間來回切換。

總覽

Chrome 開發人員工具中的 Workspace 會將網路伺服器提供的檔案，對應至電腦本機資料夾中的檔案。為本機專案啟用工作區後，您在開發人員工具「來源」面板中對檔案所做的任何變更，都會自動儲存至本機專案檔案。這項功能提供流暢的編輯體驗，讓您感覺就像直接在專案的程式碼庫中工作，同時享有開發人員工具的即時洞察資訊。

自動連結工作區的優點

自動連結工作區可免除手動設定，簡化工作區設定程序。不必手動將專案資料夾新增至開發人員工具，本機開發伺服器可以提供 Chrome 開發人員工具會自動偵測的特殊 devtools.json 檔案。這麼做有幾個優點：

加快偵錯速度：在開發人員工具中編輯檔案，不必離開瀏覽器或手動儲存，即可立即查看更新。
即時變更：變更會立即反映在您的本機檔案和瀏覽器中，加快開發速度。
免手動設定：自動對應專案檔案，縮短設定時間，特別是新專案或團隊成員加入時。

自動連結工作區的運作方式

自動工作區連線功能會讓本機開發伺服器在預先定義的路徑中公開特定 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：專案的專屬 ID (UUID 第 4 版)。這有助於開發人員工具區分不同專案。

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 第 4 版。您可以使用線上工具或指令碼產生這類檔案。
判斷專案根目錄：取得專案根目錄的絕對路徑。
建立端點：設定開發伺服器，處理對 /.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 旗標：

開啟 Chrome 並前往 chrome://flags。
搜尋「DevTools Project Settings」，並設為「Disabled」。
您也可能會看到名為「DevTools Automatic Workspace Folders」的相關標記，並可一併停用。
重新啟動 Chrome，變更就會生效。

摘要

瞭解並運用 devtools.json 機制，即可透過 Chrome 開發人員工具大幅提升本機開發工作流程。