devtools-workspace

Chrome DevTools Automatic Workspace Folders 插件 - 自动创建 DevTools 工作区配置文件

✨ 支持所有项目类型 - Vite、Webpack、Rollup、Next.js、React、Vue、Angular、Svelte 等

功能

这个插件可以自动创建 .well-known/appspecific/com.chrome.devtools.json 配置文件，使 Chrome DevTools 能够自动连接到你的项目工作区，让你直接在 DevTools 中编辑和保存文件。

支持的构建工具和框架

• ✅ Vite - 通过 Vite 插件
• ✅ Webpack - 通过 Webpack 插件
• ✅ Rollup - 通过 Rollup 插件
• ✅ Next.js - 通过 Next.js 插件
• ✅ Create React App - 通过 CLI 或 API
• ✅ Vue CLI - 通过 CLI 或 API
• ✅ Angular - 通过 CLI 或 API
• ✅ Svelte - 通过 CLI 或 API
• ✅ 静态服务器 (serve, http-server) - 通过 CLI 或 API
• ✅ 任何 Node.js 项目 - 通过 CLI 或 API

安装

npm install --save-dev devtools-workspace

使用方法

方法 1: CLI 命令行工具（推荐 - 支持所有项目类型）

自动初始化（智能检测项目类型）

# 自动检测项目类型并创建配置文件（推荐）
npx devtools-workspace auto

# 指定项目根目录
npx devtools-workspace auto --root ./my-project

# 强制覆盖已存在的配置文件
npx devtools-workspace auto --force

手动创建配置文件

# 在当前目录创建配置文件
npx devtools-workspace init

# 指定项目根目录
npx devtools-workspace init --root ./my-project

# 强制覆盖已存在的配置文件
npx devtools-workspace init --force

# 指定自定义 UUID
npx devtools-workspace init --uuid "your-custom-uuid"

检查配置文件

npx devtools-workspace check

删除配置文件

npx devtools-workspace remove

方法 2: 编程 API

const { createWorkspaceConfig, checkWorkspaceConfig, removeWorkspaceConfig } = require('devtools-workspace');

// 创建配置文件
const result = createWorkspaceConfig({
  root: './my-project',  // 可选，默认当前目录
  uuid: 'custom-uuid',  // 可选，默认自动生成
  force: false          // 可选，是否强制覆盖
});

console.log(result);
// {
//   success: true,
//   message: '配置文件创建成功',
//   path: '/path/to/.well-known/appspecific/com.chrome.devtools.json',
//   config: { workspace: { root: '...', uuid: '...' } }
// }

// 检查配置文件
const check = checkWorkspaceConfig('./my-project');
console.log(check.exists); // true/false

// 删除配置文件
const remove = removeWorkspaceConfig('./my-project');

方法 3: 构建工具插件

Vite 插件

在 vite.config.js 中配置：

import { defineConfig } from 'vite';
import vitePluginDevtoolsWorkspace from 'devtools-workspace/vite-plugin';

export default defineConfig({
  plugins: [
    vitePluginDevtoolsWorkspace({
      root: process.cwd(),  // 可选，默认当前目录
      uuid: 'custom-uuid',  // 可选，默认自动生成
      force: false          // 可选，是否强制覆盖
    })
  ]
});

Webpack 插件

在 webpack.config.js 中配置：

const WebpackDevtoolsWorkspacePlugin = require('devtools-workspace/webpack-plugin');

module.exports = {
  plugins: [
    new WebpackDevtoolsWorkspacePlugin({
      root: process.cwd(),  // 可选，默认当前目录
      uuid: 'custom-uuid',  // 可选，默认自动生成
      force: false          // 可选，是否强制覆盖
    })
  ]
};

Rollup 插件

在 rollup.config.js 中配置：

import rollupPluginDevtoolsWorkspace from 'devtools-workspace/rollup-plugin';

export default {
  plugins: [
    rollupPluginDevtoolsWorkspace({
      root: process.cwd(),  // 可选，默认当前目录
      uuid: 'custom-uuid',  // 可选，默认自动生成
      force: false          // 可选，是否强制覆盖
    })
  ]
};

Next.js 插件

在 next.config.js 中配置：

const withDevtoolsWorkspace = require('devtools-workspace/next-plugin');

module.exports = withDevtoolsWorkspace({
  // 你的 Next.js 配置
}, {
  root: process.cwd(),  // 可选，默认当前目录
  uuid: 'custom-uuid',  // 可选，默认自动生成
  force: false          // 可选，是否强制覆盖
});

方法 4: npm scripts（推荐用于所有项目类型）

在 package.json 中添加：

{
  "scripts": {
    "postinstall": "devtools-workspace auto"
  }
}

这样每次运行 npm install 后会自动检测项目类型并创建配置文件。

或者使用 init 命令：

{
  "scripts": {
    "postinstall": "devtools-workspace init"
  }
}

配置说明

创建的配置文件位于：.well-known/appspecific/com.chrome.devtools.json

内容格式：

{
  "workspace": {
    "root": "/absolute/path/to/your/project",
    "uuid": "generated-uuid-v4"
  }
}

Chrome DevTools 设置

启用功能（M-136+ 默认启用）

如果你的 Chrome 版本是 M-136 或更高，功能默认已启用。

对于较早版本（M-135），需要在 chrome://flags 中启用：

• devtools-project-settings
• devtools-automatic-workspace-folders

或者使用命令行启动：

google-chrome-canary --enable-features=DevToolsWellKnown,DevToolsAutomaticFileSystems

使用步骤

1. 安装插件：

   npm install --save-dev devtools-workspace

2. 创建配置文件（选择一种方式）：

   • 运行 npx devtools-workspace init
   • 或在 Vite 配置中添加插件
   • 或在 package.json 中添加 postinstall 脚本

3. 启动开发服务器：

   npm start
   # 或
   npm run dev

4. 在 Chrome Canary 中打开：

   • 访问 http://localhost:3000（或你的开发服务器地址）
   • 打开 DevTools（F12）
   • 在 Sources 面板中找到 Workspace 标签页

5. 连接工作区：

   • 在 Workspace 列表中会看到你的项目名称
   • 点击 "Connect" 按钮
   • 在浏览器权限提示中点击 "Allow"

版本要求

Node.js

• 最低版本: Node.js >= 14.0.0
• 推荐版本: Node.js >= 16.0.0

构建工具版本支持

• Vite: >= 3.0.0（支持 3.x, 4.x, 5.x 及未来版本）
• Webpack: >= 4.0.0（支持 4.x, 5.x 及未来版本）
• Rollup: >= 2.0.0（支持 2.x, 3.x, 4.x 及未来版本）
• Next.js: >= 12.0.0（支持 12.x, 13.x, 14.x 及未来版本）

Chrome DevTools

• 最低版本: Chrome Canary M-135 或更高版本
• 推荐版本: Chrome Canary M-136+（功能标志默认启用）

注意事项

• ⚠️ 此功能仅在 localhost 上工作
• ⚠️ 需要 Chrome Canary M-135 或更高版本
• ⚠️ 配置文件中的 root 必须是绝对路径
• ⚠️ UUID 应该是有效的 UUID v4 格式
• ⚠️ 构建工具依赖为可选（peerDependencies），只有在使用对应插件时才需要安装

项目类型检测

插件可以自动检测以下项目类型：

• Vite - 检测 vite.config.js 或 vite 依赖
• Webpack - 检测 webpack.config.js 或 webpack 依赖
• Rollup - 检测 rollup.config.js 或 rollup 依赖
• Next.js - 检测 next.config.js 或 next 依赖
• Create React App - 检测 react-scripts 依赖
• Vue CLI - 检测 @vue/cli-service 或 vue.config.js
• Angular - 检测 angular.json 或 @angular/core 依赖
• Svelte - 检测 svelte.config.js 或 svelte 依赖
• 静态服务器 - 检测 serve 或 http-server 依赖
• 通用项目 - 其他类型的项目

使用 devtools-workspace auto 命令可以自动检测项目类型并配置。

API 参考

createWorkspaceConfig(options)

创建 DevTools 工作区配置文件。

参数：

• options.root (string, 可选): 项目根目录路径，默认 process.cwd()
• options.uuid (string, 可选): 自定义 UUID，默认自动生成
• options.force (boolean, 可选): 是否强制覆盖已存在的配置文件，默认 false

返回：

{
  success: boolean,
  message: string,
  path: string,
  config?: {
    workspace: {
      root: string,
      uuid: string
    }
  }
}

checkWorkspaceConfig(root)

检查配置文件是否存在。

参数：

• root (string, 可选): 项目根目录路径，默认 process.cwd()

返回：

{
  exists: boolean,
  path: string,
  config?: {
    workspace: {
      root: string,
      uuid: string
    }
  }
}

removeWorkspaceConfig(root)

删除 DevTools 工作区配置文件。

参数：

• root (string, 可选): 项目根目录路径，默认 process.cwd()

返回：

{
  success: boolean,
  message: string,
  path: string
}

autoInit(options)

自动初始化 - 智能检测项目类型并创建配置。

参数：

• options.root (string, 可选): 项目根目录路径，默认 process.cwd()
• options.uuid (string, 可选): 自定义 UUID，默认自动生成
• options.force (boolean, 可选): 是否强制覆盖已存在的配置文件，默认 false

返回：

{
  success: boolean,
  message: string,
  path: string,
  config: {
    workspace: {
      root: string,
      uuid: string
    }
  },
  projectInfo: {
    type: string,
    buildTool: string | null,
    framework: string | null,
    hasPackageJson: boolean,
    configFiles: string[]
  }
}

许可证

MIT

相关链接

• 📦 npm 包页面
• 🐙 GitHub 仓库
• 📚 Chrome DevTools 官方文档
• 🔗 Chrome DevTools Project Settings