必须在 package.json 的 contributes.configuration 中声明配置项，否则无法显示或读取；代码中需用 vscode.workspace.getConfiguration().get() 安全获取，并监听 onDidChangeConfiguration 事件响应变更。
如何在 VSCode 插件的 settings.json 里注册自定义配置项
必须在插件根目录的 package.json 中声明 contributes.configuration，否则设置项不会出现在设置界面，也不会被 vscode.workspace.getConfiguration() 读取。
常见错误是只改了代码逻辑、漏写或写错 package.json 的配置结构。正确写法示例：
"contributes": {
"configuration": {
"type": "object",
"title": "My Extension",
"properties": {
"myExtension.enableFeature": {
"type": "boolean",
"default": true,
"description": "Enable the experimental feature"
},
"myExtension.logLevel": {
"type": "string",
"enum": ["debug", "info", "warn", "error"],
"default": "info"
}
}
}
}
-
properties下每个键名就是最终在代码中访问的完整配置路径（如"myExtension.enableFeature"） - 键名必须带命名空间前缀（推荐用插件 ID），避免与其他插件冲突
- 不支持嵌套对象作为顶层属性值；如果要分组，只能靠命名约定（如
myExtension.ui.*） - 类型声明要严格：比如想让用户输数字，
"type": "number"，不能只写"type": "string"再手动转——VSCode 不会自动校验或转换
如何在代码中安全读取用户设置值
直接调用 vscode.workspace.getConfiguration() 是唯一可靠方式；不要尝试解析 settings.json 文件路径或监听文件变更——那既不可靠也不跨平台。
关键点在于作用域和默认值处理：
- 传入字符串参数（如
"myExtension.enableFeature"）获取的是整个命名空间下的配置对象，不是单个值 - 用
.get(<key>, <defaultValue>)显式提供默认值，否则未设置时返回undefined，容易引发运行时错误 - 如果配置项属于某个语言特定范围（如只对
typescript文件生效），需传入第二个参数指定资源 URI 或语言 ID：getConfiguration("myExtension", { languageId: "typescript" }) - 监听配置变化用
onDidChangeConfiguration事件，但注意它触发时机早于配置实际更新完成，建议用setTimeout(..., 0)延迟读取最新值
为什么修改设置后插件行为没变？常见排查路径
最常被忽略的是：VSCode 缓存了配置读取结果，尤其在插件激活后首次读取未监听变更，后续修改就完全失效。
- 检查是否在插件激活函数（
activate）里只做了一次静态读取，而没绑定onDidChangeConfiguration - 确认事件监听是否过滤了目标 key：
event.affectsConfiguration("myExtension.enableFeature")，否则可能错过变更 - 打开命令面板（
Ctrl+Shift+P），运行Developer: Toggle Developer Tools，在 Console 里手动执行vscode.workspace.getConfiguration("myExtension").get("enableFeature")验证当前值是否符合预期 - 检查设置项是否被工作区或文件夹级配置覆盖：VSCode 设置有全局 → 用户 → 工作区 → 文件夹多层优先级，低优先级设置不会显示为“已设置”，但实际生效
支持多级配置（如语言专属 + 全局默认）的实际写法
VSCode 原生支持按语言 ID 覆盖配置，但需要两步配合：一是 package.json 中声明 "language-overridable": true，二是代码中用对应语言上下文读取。
例如想让 logLevel 在 Python 文件中默认为 "debug"，其他地方保持 "info"：
"myExtension.logLevel": {
"type": "string",
"enum": ["debug", "info", "warn", "error"],
"default": "info",
"language-overridable": true
}
- 在
package.json的configuration.properties里为该字段添加"language-overridable": true - 用户可在设置 UI 中点击右上角“{}”图标，切换到
[python]标签页单独设置 - 代码中读取时，若当前编辑器是 Python 文件，应使用：
vscode.workspace.getConfiguration("myExtension", vscode.window.activeTextEditor?.document.uri).get("logLevel") - 注意：不传 URI 时读取的是全局/用户级配置；传了 URI 才会合并语言级覆盖值
语言覆盖配置不会自动广播到所有打开的编辑器，每次读取都需基于当前上下文重新获取——这点容易误以为“设置没生效”。
