ローカル開発中に現れる GET /.well-known/appspecific/com.chrome.devtools.json とは何か

フロントエンドの開発をしているとき、開発サーバーのログで以下のような覚えのないリクエストが記録されているのを見たことがあるのではないでしょうか？

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

これは Chrome DevTools がローカルプロジェクトを Workspace として自動検出するためのリクエストです。 このリクエストは DevTools を開いたときだけ送られ、開発サーバーが 404 を返すのは正しい挙動でこのリクエスト自体は無害です。

開発サーバーで /.well-known/appspecific/com.chrome.devtools.json から有効な JSON を返すと Chrome DevTools の Sources パネルとローカルのプロジェクトを簡単に関連付けられます。関連付けた後は、DevTools で編集した HTML、CSS、JavaScript をローカルファイルへ自動で反映できるようになります。

この記事では、このリクエストが送られる理由を確認し、実際に Node.js の開発サーバーから JSON を返して、Chrome DevTools で編集した CSS がローカルファイルへ保存されるところまでを紹介します。さらに Vite と Next.js の React コンポーネントを DevTools から変更し、開発サーバーの画面へ反映されることも確認します。

Chrome DevTools の Workspace 自動検出とは

Automatic Workspace Folders は、Chrome DevTools がローカル開発サーバーからプロジェクトの情報を取得し、Workspace の接続候補を自動的に表示する機能です。

DevTools を開いた状態で localhost のページを表示すると、Chrome DevTools は同じオリジンの以下の URL へリクエストを送ります。

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

DevTools がこの JSON を取得しようとするのは、検証しているページのオリジンが localhost の場合だけです。ローカル開発のための機能であり、localhost 以外のページを開いても Chrome がこのリクエストを送ることはありません。

開発サーバーがこの URL を処理しなければ、通常の存在しないパスと同じように 404 が返ります。Chrome DevTools のトラブルシューティングでも、機能を使わない場合、この 404 は無視できると説明されています。

/.well-known/ は、あるオリジンについて決められたメタデータを取得するための共通の場所です。RFC 8615 により、HTTP や HTTPS の URL では /.well-known/ から始まるパスがこの用途のために予約されています。アプリケーションごとに URL を推測する必要がなく、名前の衝突も避けられます。

appspecific は、個々のアプリケーションが専用のファイルを置くために IANA の Well-Known URI レジストリへ provisional（暫定）登録されている接尾辞です。appspecific の登録文書では、ファイル名をアプリケーションが管理するドメイン名に基づいて決めるよう要求しています。

com.chrome.devtools.json は chrome.com を逆順にした名前空間を使っています。これにより、同じ appspecific ディレクトリを使う別のアプリケーションと衝突しにくくなります。

Automatic Workspace Folders は Chrome 135 で追加されました。当初は試験運用のためフラグが必要でしたが、プロジェクト設定の取得は Chrome 136、自動的なファイルシステム接続は Chrome 137 から既定で有効になりました。古い記事にある chrome://flags の変更は、現在の Chrome では不要です。

この機能が解決するのは、従来の Workspace 設定が見つけづらく、プロジェクトや別の checkout を開くたびにフォルダを手動で追加・削除する必要があったという問題です。開発サーバーが現在のプロジェクトを通知することで、DevTools はページを開いている間だけ対応するフォルダを接続できます。

com.chrome.devtools.json の内容

開発サーバーは、対象の URL へ次の形式の JSON を返します。

{
  "workspace": {
    "root": "/Users/yourname/path/to/project",
    "uuid": "9a78c0dd-00ed-4b52-8e49-19a8e5cd1543"
  }
}

workspace.root は、Chrome が動いているコンピューター上のプロジェクトルートを表す絶対パスです。相対パスでは動作しません。開発サーバーがコンテナーや WSL で動いている場合は、サーバー内のパスではなく、Chrome から到達できるパスへ変換する必要があります。

workspace.uuid はプロジェクトを識別する有効な UUID です。Chrome のドキュメントではランダムな UUID v4 が推奨されています。

この UUID はリクエストごとに生成してはいけません。Chromium の実装では、ユーザーが許可した root と UUID の組み合わせを Chrome のプロファイルへ保存します。同じ組み合わせが再び返されたときは、保存済みの許可を使って Workspace を再接続します。UUID が毎回変わると別のプロジェクト設定として扱われ、再接続できません。

プロジェクトごとにランダムな値を 1 度生成し、開発サーバーのキャッシュなどへ永続化するのが想定された使い方です。

Node.js の開発サーバーから JSON を返す

ここからは Node.js の標準 API だけを使って動作を確認します。次の例では、HTML と CSS に加えて com.chrome.devtools.json を返す開発サーバーを作成します。

import { createServer } from "node:http";
import { readFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
 
// プロジェクトルートの絶対パスを取得する
const projectRoot = dirname(fileURLToPath(import.meta.url));
// UUID は開発サーバーの起動ごとに変わらないよう固定値を使う
const workspaceUuid = "9a78c0dd-00ed-4b52-8e49-19a8e5cd1543";
 
const files = new Map([
  ["/", { path: "index.html", type: "text/html; charset=utf-8" }],
  ["/styles.css", { path: "styles.css", type: "text/css; charset=utf-8" }],
]);
 
const server = createServer(async (request, response) => {
  const url = new URL(request.url ?? "/", `http://${request.headers.host}`);
 
  console.log(`${request.method} ${url.pathname}`);
 
  // URL が /.well-known/appspecific/com.chrome.devtools.json の場合は JSON を返す
  if (
    url.pathname === "/.well-known/appspecific/com.chrome.devtools.json"
  ) {
    response.writeHead(200, { "Content-Type": "application/json" });
    response.end(
      JSON.stringify({
        workspace: {
          root: projectRoot,
          uuid: workspaceUuid,
        },
      }),
    );
    return;
  }
 
  // 存在しないパスの場合は 404 を返す
  const file = files.get(url.pathname);
  if (!file) {
    response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
    response.end("Not Found");
    return;
  }
 
  // 通常のリクエストの場合は index.html や styles.css を返す
  const content = await readFile(join(projectRoot, file.path));
  response.writeHead(200, { "Content-Type": file.type });
  response.end(content);
});
 
server.listen(8000, "localhost", () => {
  console.log("Server running at http://localhost:8000");
});

url.pathname が /.well-known/appspecific/com.chrome.devtools.json の場合、開発サーバーは JSON を返すようにしています。JSON の workspace.root には、開発サーバーが動作しているコンピューター上のプロジェクトルートの絶対パスを返します。workspace.uuid には、開発サーバーの起動ごとに変わらない固定値を使っています。

if (
  url.pathname === "/.well-known/appspecific/com.chrome.devtools.json"
) {
  response.writeHead(200, { "Content-Type": "application/json" });
  response.end(
    JSON.stringify({
      workspace: {
        root: projectRoot,
        uuid: workspaceUuid,
      },
    }),
  );
  return;
}

DevTools からローカルファイルを編集する

サーバーを起動し、Chrome で http://localhost:8000 を開いてから DevTools を開きます。

node server.mjs

このとき、開発サーバーには次のリクエストが記録されました。最後のリクエストが Chrome DevTools による Workspace の自動検出です。

GET /
GET /styles.css
GET /.well-known/appspecific/com.chrome.devtools.json

DevTools の Sources > Workspaces を開くと、chrome-devtools-automatic-workspaces という接続候補と「ワークスペースに接続」ボタンが表示されました。

chrome-devtools-automatic-workspaces の「ワークスペースに接続」をクリックすると、「DevTools にファイルの編集を許可しますか？」というダイアログが表示されます。

「許可する」をクリックすると、Workspace にプロジェクト内のファイルが表示されます。index.html と styles.css にはネットワーク上のリソースへ対応付けられたことを示す緑色のマークも表示されました。

Workspace で styles.css を開き、royalblue を tomato に変更して Cmd + S で保存します。その後ファイルを確認すると、styles.css の内容が DevTools で変更した通りに更新されていることが確認できました。

なお、保存されるのは Workspace にマッピングされたソースファイルへの変更です。Elements パネルで DOM を直接書き換えただけでは、HTML ファイルへ変更は保存されません。ビルドツールが変換したコードを表示している場合は、source map があれば DevTools が元のソースへのマッピングを試みます。

許可している Workspace の一覧は、DevTools の Settings > Workspace で確認できます。不要になった場合は、一覧から削除して接続を解除できます。

Vite ではプラグインを追加する

2026 年 8 月 29 日時点では、Vite 本体は com.chrome.devtools.json のエンドポイントを提供していません。Chrome DevTools チームのリポジトリで公開されている vite-plugin-devtools-json を利用できます。

npm install -D vite-plugin-devtools-json

Vite の設定へプラグインを追加します。

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import devtoolsJson from "vite-plugin-devtools-json";
 
export default defineConfig({
  plugins: [react(), devtoolsJson()],
});

プラグインは既定で Vite の config.root を workspace.root として返します。UUID は初回起動時に生成され、その後は Vite のキャッシュへ保存されます。モノレポなどで Vite のルートと Workspace にしたいディレクトリが異なる場合は、projectRoot オプションで絶対パスを指定できます。

先に触れたコンテナーや WSL のパスの問題にも対応しており、既定で有効な normalizeForWindowsContainer オプションが Linux 側のパスを Chrome から到達できる UNC 形式へ変換します。

Vite 本体へ組み込む案も議論されました。しかし Chrome 固有の機能を本体へ含めることや、今後 JSON の用途が増えた場合の変更を Chrome 側で管理しやすくすることから、独立したプラグインを支持する意見が出ています。現時点でも Vite 本体ではなくプラグインとして提供されています。

実際に動作を確認してみましょう。npm run dev で開発サーバーを起動し、Sources > Workspaces から vite-react へ接続します。Workspace で src/App.jsx を開き、<p> の文言を変更して保存すると、実際の src/App.jsx が更新され、手動でページを再読み込みせずに表示も切り替わりました。このように React のソースコードであっても変更が反映されるのは面白いところですね。

Next.js は開発サーバーが既定で応答する

Next.js は PR #80260 で、開発サーバーが com.chrome.devtools.json を返す処理を追加しました。この変更は 15.4.0-canary.76 から入り、安定版では 15.4.1 以降に含まれています。15.4.0 は PR がマージされる前に公開されているため、このエンドポイントを持っていない点に注意してください。

next dev では追加設定なしで、プロジェクトルートと UUID を含む JSON が返ります。UUID は .next 配下のキャッシュへ保存され、ページを再読み込みしても同じ値が使われます。一方、next build 後の本番サーバーではこの URL は 404 になります。

独自の挙動に変更したい場合は、public ディレクトリや Route Handler から同じパスへレスポンスを返すことで既定の処理を上書きできます。

Next.js の場合も同様に、DevTools で React コンポーネントを編集して保存すると、変更を検知して画面へ反映されることが確認できました。

まとめ

• GET /.well-known/appspecific/com.chrome.devtools.json は、Chrome DevTools がローカルプロジェクトの Workspace を自動検出するために送るリクエストである
• Workspace を利用しない開発サーバーが 404 を返しても、通常は無害であり対応する必要はない
• 有効な root と安定した UUID を返すと、Workspace の接続候補が DevTools に表示される
• ユーザーの許可後に DevTools から HTML、CSS、JavaScript をローカルファイルへ保存できる
• Vite では vite-plugin-devtools-json を追加でき、Next.js 15.4.1 以降の開発サーバーは既定でエンドポイントを提供する
• 絶対パスの漏えいを防ぐため、com.chrome.devtools.json はローカル開発時だけ配信する

参考

• Automatic Workspace connection in Chrome DevTools
• Set up workspaces to save changes to source files
• Chromium DevTools Ecosystem Guide - Automatic Workspace Folders
• Chromium devtools_file_helper.cc
• ChromeDevTools/vite-plugin-devtools-json
• [devtools] Implement default /.well-known/appspecific/com.chrome.devtools.json endpoint in dev - vercel/next.js