VSCode代码提示优先级_让局部变量排在全局建议之前

VSCode局部变量补全不靠默认排序，需同时设置"editor.suggest.sortSelectedItems": false和"editor.suggest.localityBonus": true，并用语言作用域配置（如"[ja vascript]"）生效，否则本地变量权重被历史选择覆盖。

局部变量默认不会自动排在全局建议之前——这是 VSCode 补全排序的常见误解。真正起作用的是 editor.suggest.localityBonus，且它只在启用时才让当前作用域内定义的符号（如 const foo = 1）获得权重加成，但不会“强制置顶”，更不保证压过语言服务器返回的高优先级项（比如 console.log 或类型定义里的方法）。

为什么局部变量经常被“埋”在补全列表第二页

话说回来，为什么你刚定义的变量，一敲名字却总在补全列表里“潜水”呢？这得从 VSCode 1.80+ 版本说起，它移除了 editor.suggestSorting 选项。现在的补全顺序，其实是两股力量博弈的结果：一股是语言服务器返回的 sortText（这部分由后端控制，用户基本动不了），另一股是客户端对匹配项的动态权重（这部分你还能调一调）。editor.suggest.localityBonus 就属于后者，但它充其量只是个“加分项”，而不是“插队特权”。如果语言服务器给 Array.prototype.map 这类全局 API 返回了极低的 sortText 值，哪怕你在当前函数里刚写了 let map = () => {}，你的局部 map 也大概率排不上去。

• 局部变量压根没出现？ 先别急着怪排序，得确认它是否被语言服务器识别了。比如，是不是忘了写 const 或 let，或者变量虽然在非顶层作用域，但 TypeScript/Ja vaScript 的语义检查没开？
• 定义了 const utils = {...}，但敲 utils. 后看不到自己的方法？ 这通常意味着语言服务器没能正确推导出类型，问题出在类型推断上，跟排序配置关系不大。
• 最关键的一步： 必须关闭 editor.suggest.sortSelectedItems。否则，就算你手动选了5次 myHelper，下次触发补全时，它依然可能被 Math.random 这类高频全局项挤到后面去。

必须设的两个配置项

想让局部变量“浮”上来，单靠一个 localityBonus 是远远不够的。必须配合禁用智能重排，才能让“本地性”这个特性真正生效。具体是哪两个配置呢？

• "editor.suggest.sortSelectedItems": false —— 这是关键开关。不关掉它，你之前的历史选择行为就会覆盖掉对局部作用域变量的偏好。
• "editor.suggest.localityBonus": true —— 这个选项负责给当前文件、当前函数内声明的变量和函数增加匹配权重。

这两个配置必须同时写进 settings.json，缺一不可。如果只开 localityBonus，效果会非常微弱。因为 VSCode 在你选中一项后，会立刻把它“重排”到顶部，这个操作很可能就把刚刚给局部变量加的那点“本地分”给冲掉了。

语言级设置比工作区设置更有效

想让 Ja vaScript 或 TypeScript 文件优先响应局部变量，有个更精准的办法：别只改动用户级或工作区级的 settings.json。直接使用语言作用域配置，优先级更高，效果也更直接。

{
  "[ja vascript]": {
    "editor.suggest.sortSelectedItems": false,
    "editor.suggest.localityBonus": true,
    "editor.suggest.showFunctions": true,
    "editor.suggest.showVariables": true
  },
  "[typescript]": {
    "editor.suggest.sortSelectedItems": false,
    "editor.suggest.localityBonus": true,
    "editor.suggest.showFunctions": true,
    "editor.suggest.showVariables": true
  }
}

这里有个细节需要注意：[ja vascript] 这类带方括号的配置会覆盖同名的普通设置，并且对 .js 和 .jsx 文件生效；同理，[typescript] 对 .ts 和 .tsx 文件生效。千万别写成 "ja vascript": { ... }（少了方括号），那样是无效的。

容易被忽略的干扰项

即使你把上面的配置都配齐了，以下这些情况仍然可能让你的局部变量“隐身”：

• 插件干扰： 安装了 Prettier、Auto Import 这类插件——它们可能会向补全列表注入大量全局符号（比如自动引入的 React 组件或方法），从而稀释了本地项的权重。如果怀疑是插件问题，可以尝试临时禁用它们来测试。
• 索引问题： 文件没有被语言服务器正确索引。比如，文件不在 jsconfig.json 或 tsconfig.json 的包含路径内。这时候，localityBonus 想给你加分，也找不到可以加成的变量。
• 输入前缀太短： 只输入一个字母（比如 m）就触发补全，VSCode 会优先匹配所有包含 m 的全局 API，导致局部变量被淹没。不妨多输入几个字母（比如 my）再触发补全，效果往往会更明显。

说到底，补全排序的瓶颈，很多时候并不在客户端的配置上。真正的关键在于，语言服务后端能否“看见”并正确分析你的局部定义。补全不是一个纯粹的前端逻辑游戏，它严重依赖于后端的语义分析结果。