补全不弹出大概率是registercompletionitemprovider首个参数语言id不匹配，必须精确对应右下角显示的语言模式（如python、typescript），而非文件后缀；触发字符需真实存在于输入流，且需显式注册关键语言id并正确配置inserttext与snippet。
补全提供器注册必须匹配语言ID和触发字符
VSCode插件里写完 provideCompletionItems 逻辑，补全却完全不弹——大概率是 registerCompletionItemProvider 的第一个参数没对上。它不是“支持所有语言”的万能通配符，而是精确匹配当前文件的语言ID（比如 python、typescript、javascript），不是文件后缀名。
常见错误：
- 用
'*'声称支持所有语言，但实际只对部分语言生效（尤其在新版本中已被限制） - 注册了
'typescript'，但文件语言模式是JavaScript（右下角显示 JS，不是 TS） - 触发字符设为
'.'，但在 Python 中需要输入'.'才触发；而 JSX 中可能需额外监听'{'或'('
实操建议：
- 先确认当前文件语言ID：按
Ctrl+Shift+P→ 输入Change Language Mode→ 看右下角显示的名称，这就是你要注册的ID - 注册时显式列出关键语言：
vscode.languages.registerCompletionItemProvider(['typescript', 'javascript'], new Completer(), '.', '(') - 触发字符必须真实存在于用户输入流中，不能靠模拟；例如想在输入
fetch后补全.then()，得监听'.'，而不是等用户敲完fetch再主动弹窗
补全项插入文本必须区分 insertText 和 documentation
很多插件开发者把 insertText 当成“显示文字”，结果补全后代码变成 console.log()console.log() ——这是混淆了 label、insertText 和 documentation 的职责。
label 是列表里显示的名称（如 log），insertText 是真正插入编辑器的内容（如 log($1)），documentation 是悬浮提示（如 “输出日志”）。漏掉 insertText 或写错格式，会导致补全行为异常。
实操建议：
- 用
vscode.SnippetString处理带占位符的插入，例如new vscode.SnippetString('log(${1:msg})')，否则$1会被当字面量插入 - 避免直接拼接字符串作为
insertText，尤其含括号、引号时易被转义或截断 - 若要补全函数调用并保留光标在括号内，必须用 snippet，纯字符串无法实现 tab 导航
跨文件符号补全依赖语言服务器索引，插件无法绕过
你写了完美的补全逻辑，但用户输入 utils. 后啥都不出来？别怪插件——VSCode 插件层拿不到项目级符号表。所有 import 路径解析、类型推导、跨文件成员枚举，都由底层语言服务器（如 Pylance、TypeScript Server、Intelephense）完成。插件只能基于已有索引做“增强”，不能凭空造符号。
这意味着：
- 没有
jsconfig.json或tsconfig.json，TS/JS 项目里@/别名补全永远失效，插件加再多逻辑也没用 - Python 项目没生成
__pycache__或没运行composer dump-autoload（Laravel 场景），自定义 helper 函数不会出现在符号表里 - 插件里调
vscode.workspace.getConfiguration()查不到语言服务器是否就绪，唯一可靠方式是监听vscode.languages.onDidChangeDiagnostics或检查输出面板日志
实操建议：
- 插件文档里必须写明前置条件：“需已安装并启用 Pylance” 或 “要求项目根目录存在 tsconfig.json”
- 在
provideCompletionItems开头加简单守卫：若vscode.window.activeTextEditor?.document.languageId !== 'python'，直接返回空数组，避免无谓计算 - 不要尝试在插件里重复实现路径解析（如
@/utils→src/utils），那是语言服务器的事
调试补全插件必须看 Output 面板的 Language Server 日志
补全不触发，console.log 在插件里打印了，但没反应？别只盯着 extension.ts 断点——绝大多数问题出在语言服务器与插件的协作链路上，而非插件本身逻辑。
关键排查路径：
- 打开 Output 面板（
Ctrl+Shift+U），切换到对应语言 Server（如TypeScript Server、Pylance），搜error或Starting，确认服务已加载且无崩溃 - 检查插件激活日志：在 Output →
Log (Extension Host)里找你的插件名，确认activate被调用且无报错 - 用
vscode.commands.executeCommand('editor.action.triggerSuggest')手动唤出建议框，如果仍为空，说明提供器根本没被调用；如果弹出但内容不对，才是插件逻辑问题
容易被忽略的一点：插件启用后，VSCode 不会自动重启语言服务器。改了 tsconfig.json 或新增了 files autoload，必须手动执行 Developer: Restart Extension Host 或重载窗口，否则索引不会更新。
