provideCompletionItems未被调用的主因是插件未激活或语言选择器不匹配，需检查activationEvents配置、语言ID大小写一致性及registerCompletionItemProvider是否在激活后执行。
VSCode 插件的自动补全（IntelliSense）功能调试，核心在于确认语言服务器（LSP）是否正确注册、响应是否符合协议规范、以及客户端能否识别并渲染提示项——多数问题出在 provideCompletionItems 返回结构不合法或触发条件未满足。
为什么 provideCompletionItems 没有被调用？
这是最常见卡点：不是逻辑没写，而是 VSCode 根本没发请求。
- 检查
activationEvents是否包含对应语言或文件关联，例如"onLanguage:json"或"onCommand:myExtension.triggerCompletion"；漏配会导致插件未激活，registerCompletionItemProvider甚至不会执行 - 确认
languages.registerCompletionItemProvider调用发生在插件激活后，且传入的selector与当前编辑器语言 ID 严格匹配（注意大小写，typescript≠TypeScript） - 打开命令面板（
Ctrl+Shift+P），运行Developer: Toggle Developer Tools，在 Console 中输入monaco.languages.getLanguages()查看当前注册的语言列表，验证目标语言是否存在
返回的补全项不显示或显示为空？
VSCode 对 CompletionItem 字段有强校验，任意字段类型/层级错误都会静默丢弃整个项。
-
label必须是字符串（不能是undefined或对象），且非空；label是唯一必填字段，其他都可选 - 若使用
insertText，确保它是string或SnippetString；传入普通对象或带换行的模板字面量易导致渲染失败 - 避免在
resolveCompletionItem中异步修改label或documentation—— VSCode 可能已开始渲染，此时修改无效 - 简单验证：直接返回一个最小可行项：
{ label: "test", kind: monaco.languages.CompletionItemKind.Text }，再逐步加字段排查
补全触发时机不对（比如要按 Ctrl+Space 才出现）？
默认情况下，VSCode 仅对部分语言内置触发字符（如 .、:），自定义语言需显式配置。
- 在插件的
package.json中为对应语言添加configurationDefaults，指定editor.quickSuggestions和editor.suggestOnTriggerCharacters - 更可靠的方式是在
registerCompletionItemProvider的第三个参数传入触发字符数组，例如['.', '-', '_']；该数组决定哪些输入会立即拉起补全，无需手动唤出 - 注意：如果同时设置了
suggestOnTriggerCharacters: false（常见于某些基础语言配置），插件级的触发字符也会被禁用
调试时看不到 LSP 响应内容？
当使用 Language Server Protocol（如通过 vscode-languageclient）时，网络层日志比前端更关键。
- 启动插件时加环境变量：
LOG_LEVEL=3（或设置trace: 'verbose'），并在客户端初始化时启用outputChannel输出原始 JSON-RPC 报文 - 重点检查
textDocument/completion请求的position是否准确（行/列从 0 开始）、context.triggerKind是否为Invoked/TriggerCharacter - LSP 服务端返回的
items数组中每个元素必须含label，且不能有非法字段（如__proto__、constructor）——这些会被 JSON 序列化过滤，导致空数组
真正难调的往往不是逻辑，而是协议字段的隐式约束和 VSCode 的静默容错机制。建议每次只改一个字段，用最小 payload 过一遍生命周期：触发 → 请求 → 响应 → 渲染，中间任何一环断掉，就回到对应环节的日志里找原始 JSON。
