配置读取与修改

插件通过 WorkspaceConfiguration API 读取与修改配置。本文从读取基础到多级写入，完整讲解配置的读写能力。

获取配置对象

vscode.workspace.getConfiguration 是配置入口：

import * as vscode from 'vscode';

// 获取插件配置段（section）
const config = vscode.workspace.getConfiguration('mylinter');

// 不传 section 获取所有配置
const all = vscode.workspace.getConfiguration();

getConfiguration('mylinter') 返回一个上下文限定在 mylinter 前缀下的配置对象，后续 get/update 都相对该前缀。

读取配置值

get 读取

const config = vscode.workspace.getConfiguration('mylinter');

// 读取具体配置项
const enable = config.get<boolean>('enable');              // true
const maxWarnings = config.get<number>('maxWarnings');     // 100

// 读取对象/数组
const rules = config.get<Record<string, string>>('rules');
const ignore = config.get<string[]>('ignoreFiles');

读取嵌套配置

点号访问嵌套字段：

// 配置结构：mylinter.rules.no-console
const config = vscode.workspace.getConfiguration('mylinter');
const noConsole = config.get<string>('rules.no-console');

默认值兜底

// 配置未设置时返回默认值
const timeout = config.get<number>('timeout', 5000);

// 没有 default 且用户未设置时返回 undefined
const custom = config.get<string>('custom');   // undefined

update 修改配置

configuration.update(key, value, target) 写入配置：

const config = vscode.workspace.getConfiguration('mylinter');

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

// 写入工作区级配置（settings.json）
await config.update('maxWarnings', 200, vscode.ConfigurationTarget.Workspace);

// 写入工作区文件夹级配置（.vscode/settings.json）
await config.update(
  'maxWarnings',
  50,
  vscode.ConfigurationTarget.WorkspaceFolder
);

ConfigurationTarget 三种目标

目标	写入位置	生效范围
Global	用户 settings.json	所有窗口
Workspace	工作区 .vscode/settings.json	当前工作区
WorkspaceFolder	文件夹 .vscode/settings.json	当前文件夹
WorkspaceFolder（无 folder）	同 Workspace	多根回退

update 注意事项

// 传入 undefined 删除配置项（恢复默认）
await config.update('custom', undefined, vscode.ConfigurationTarget.Global);

// 更新嵌套字段：传完整对象
const rules = config.get<Record<string, string>>('rules', {});
await config.update('rules', { ...rules, 'no-console': 'warning' },
  vscode.ConfigurationTarget.Workspace);

// update 是异步的，写入后可立即读取

读取 UI 控制修改

除了直接修改配置，也可以调用设置 UI 让用户确认：

// 展示设置编辑器并聚焦特定配置
vscode.commands.executeCommand(
  'workbench.action.openSettings',
  '@ext:mypublisher.mylinter mylinter.rules'
);

inspect 检查值来源

inspect 返回配置值的完整来源信息：

const config = vscode.workspace.getConfiguration('mylinter');
const inspected = config.inspect<number>('maxWarnings');

console.log(inspected);
// {
//   defaultValue: 100,              // 声明中的默认值
//   globalValue: undefined,         // 用户级覆盖
//   workspaceValue: 200,            // 工作区级覆盖
//   workspaceFolderValue: 50,       // 文件夹级覆盖
//   defaultLanguageValue: undefined,
//   globalLanguageValue: undefined,
//   workspaceLanguageValue: undefined,
//   workspaceFolderLanguageValue: undefined,
//   languageIds: undefined,
//   key: 'mylinter.maxWarnings'
// }

inspect 的用途

场景	用法
判断值来自哪一层	检查 globalValue/workspaceValue 是否非空
检测用户是否自定义	globalValue ?? workspaceValue ?? undefined
分层重置	删除某一层的覆盖
语言级配置检测	查看 languageIds

// 重置某一层的自定义值
if (inspected.workspaceValue !== undefined) {
  await config.update('maxWarnings', undefined,
    vscode.ConfigurationTarget.Workspace);
}

配置写入流程

用户设置界面                插件 update
      │                        │
      ▼                        ▼
settings.json          ConfigurationTarget
  ├─ 用户级                 ├─ Global
  ├─ 工作区级               ├─ Workspace
  └─ 文件夹级               └─ WorkspaceFolder
      │
      ▼
getConfiguration 合并解析（越具体优先级越高）
      │
      ▼
config.get(key) 返回最终值

优先级

值解析时从高到低：语言级 > 文件夹级 > 工作区级 > 用户级 > 默认值。

完整读写示例

import * as vscode from 'vscode';

export async function toggleLinter(
  folder?: vscode.WorkspaceFolder
): Promise<void> {
  const config = vscode.workspace.getConfiguration('mylinter');

  // 读取当前值（考虑 folder）
  const current = folder
    ? vscode.workspace.getConfiguration('mylinter', folder.uri)
    : config;
  const enable = current.get<boolean>('enable', true);

  // 写入新值
  const target = folder
    ? vscode.ConfigurationTarget.WorkspaceFolder
    : vscode.ConfigurationTarget.Workspace;

  await current.update('enable', !enable, target);
}

针对资源读取配置

getConfiguration 可传入 URI 读取资源级配置：

// 读取某个文件目录的配置
const fileConfig = vscode.workspace.getConfiguration(
  'mylinter',
  vscode.Uri.file('/repo/src/main.ts')
);

// 读取某个语言级配置
const langConfig = vscode.workspace.getConfiguration('mylinter', {
  languageId: 'typescript'
});

const semanticErrors = langConfig.get<boolean>('semanticErrors');

配置读取最佳实践

实践	说明
集中读取	用 getter 函数包装，避免散落
默认值兜底	所有 get 提供默认值
缓存 + 监听	高频读取缓存，配合变更监听刷新
按需传 URI	资源级配置务必传 URI 才能生效

配置读取修改的 API 简洁清晰，配合变更监听即可实现配置驱动的动态行为，下一篇详解变更监听。