Workspace API

vscode.workspace 命名空间是插件访问「工作区环境」的总入口：了解当前打开的工作区、读写配置、监听配置变化。几乎所有实用插件都会用到它。

workspaceFolders 多工作区

workspace.workspaceFolders 返回当前打开的所有工作区文件夹：

import * as vscode from 'vscode';

// 获取工作区文件夹列表
const folders = vscode.workspace.workspaceFolders;
if (folders) {
  folders.forEach((folder) => {
    console.log(folder.name);      // 文件夹名
    console.log(folder.uri.fsPath); // 绝对路径
    console.log(folder.index);      // 索引
  });
}

// 当前文件夹数量
const count = vscode.workspace.workspaceFolders?.length ?? 0;

工作区类型

场景	workspaceFolders
单文件夹打开	1 个元素
多根工作区（工作区文件）	多个元素
仅打开文件（无文件夹）	undefined

判空与遍历

if (!vscode.workspace.workspaceFolders) {
  vscode.window.showWarningMessage('请先打开一个文件夹');
  return;
}

// 遍历所有文件夹
for (const folder of vscode.workspace.workspaceFolders) {
  // 处理每个工作区
}

getConfiguration 配置读取

workspace.getConfiguration 读取配置（即 contributes.configuration 定义的设置项）：

// 读取整个 section
const config = vscode.workspace.getConfiguration('myExt');

// 读取具体配置项（带默认值）
const enabled = config.get<boolean>('enabled', true);
const theme = config.get<string>('theme', 'dark');
const maxSize = config.get<number>('maxSize', 1024);

配置作用域

// 获取某个文件夹的配置
const folderConfig = vscode.workspace.getConfiguration(
  'myExt',
  vscode.workspace.workspaceFolders?.[0]
);

// 读取配置的完整信息（来源等）
const inspected = config.inspect('enabled');
// inspected: { defaultValue, globalValue, workspaceValue, workspaceFolderValue }

修改配置

configuration.update 写回配置：

// 写入用户级配置
await config.update('enabled', false, vscode.ConfigurationTarget.Global);

// 写入工作区级配置
await config.update(
  'theme',
  'light',
  vscode.ConfigurationTarget.Workspace
);

Target	作用域
Global	用户所有项目生效
Workspace	当前工作区生效
WorkspaceFolder	单个文件夹生效

完整读取示例

const config = vscode.workspace.getConfiguration('myExt');
const settings = {
  enabled: config.get('enabled', false),
  interval: config.get('interval', 60),
  formats: config.get('formats', ['.md', '.txt']),
  nested: config.get('nested.subKey')
};

配置变更监听 onDidChangeConfiguration

监听配置变化，实时响应：

context.subscriptions.push(
  vscode.workspace.onDidChangeConfiguration((event) => {
    // 检查是否影响本插件配置
    if (event.affectsConfiguration('myExt')) {
      console.log('配置已变更，重新加载...');
      reloadSettings();
    }

    // 检查具体某项
    if (event.affectsConfiguration('myExt.theme')) {
      console.log('主题配置变更');
    }
  })
);

affectsConfiguration

event.affectsConfiguration(section) 判断变更是否与指定配置相关：

用法	说明
affectsConfiguration('myExt')	是否影响 myExt 整个 section
affectsConfiguration('myExt.theme')	是否影响具体某项

只有相关配置变更时才重新处理，避免无效刷新。

workspace trust 工作区信任

VS Code 的工作区信任机制：打开不信任的文件夹时，插件默认不运行：

import * as vscode from 'vscode';

// 检查是否信任
const isTrusted = vscode.workspace.isTrusted;
if (!isTrusted) {
  vscode.window.showWarningMessage('当前工作区不受信任');
}

// 监听信任状态变化
context.subscriptions.push(
  vscode.workspace.onDidGrantWorkspaceTrust(() => {
    console.log('工作区已获得信任');
    initializeExtension();
  })
);

声明信任需求

高权限插件可在 package.json 声明需要信任：

{
  "capabilities": {
    "untrustedWorkspaces": {
      "supported": false,
      "description": "此插件需要工作区信任"
    }
  }
}

配置	行为
supported: true	可在非信任工作区运行
supported: false	需要信任才能运行
description	提示文字

其他常用 Workspace API

API	用途
workspace.openTextDocument	打开文档
workspace.workspaceFile	工作区文件路径
workspace.fs	文件系统操作
workspace.findFiles	搜索文件
workspace.getWorkspaceFolder(uri)	获取 URI 所在文件夹

完整示例：配置驱动插件

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  // 读取配置初始化
  let enabled = readConfig();

  // 监听配置变更实时生效
  context.subscriptions.push(
    vscode.workspace.onDidChangeConfiguration((event) => {
      if (event.affectsConfiguration('myExt')) {
        enabled = readConfig();
        updateStatusBar();
      }
    })
  );

  // 遍历工作区执行操作
  context.subscriptions.push(
    vscode.commands.registerCommand('myExt.processWorkspace', async () => {
      const folders = vscode.workspace.workspaceFolders;
      if (!folders || !enabled) {
        vscode.window.showWarningMessage('未启用或未打开工作区');
        return;
      }

      for (const folder of folders) {
        const files = await vscode.workspace.findFiles(
          '**/*.ts',
          '**/node_modules/**'
        );
        vscode.window.showInformationMessage(
          `${folder.name} 有 ${files.length} 个 TS 文件`
        );
      }
    })
  );
}

function readConfig(): boolean {
  return vscode.workspace
    .getConfiguration('myExt')
    .get('enabled', false);
}

常见问题

问题	处理
workspaceFolders 为空	未打开文件夹，先判空
配置读不到	检查 section 名与配置定义
配置修改不生效	确认 target 作用域
监听不触发	检查 affectsConfiguration 匹配

Workspace API 让插件感知并操作整个工作区环境，是编写「项目级」工具的基础。