VSCode代码提示过滤_屏蔽不需要的全局变量补全

应修改 tsconfig.json 的 “lib” 和 “types” 配置以精准控制全局补全

你是否也遇到过这样的困扰：在编写 Node.js 脚本或工具库时，代码补全列表里总是充斥着 window、document 这类浏览器环境的全局变量？这不仅干扰视线，更降低了编码效率。问题的根源，往往在于 TypeScript 语言服务对全局作用域的“过度暴露”。

为什么 globalThis 和 window 的属性总在补全里刷屏？

VSCode 的智能补全本身并不决定该显示什么，它完全依赖于底层的 TypeScript 语言服务。而 TypeScript 判断哪些全局变量“可用”，其依据就是项目的 tsconfig.json 配置文件，尤其是其中的 “lib” 字段。

简单来说，如果你在写一个后端服务，但 “lib” 里包含了 “dom”，那么所有 DOM API（如 localStorage、fetch）都会理所当然地成为补全候选。这就像在厨房里找螺丝刀，工具箱里却混进了一堆厨具。

具体来说，需要检查两个地方：

• 项目级配置：打开项目根目录的 tsconfig.json，查看 “compilerOptions” 下的 “lib” 数组。如果其中包含 “dom”，那么浏览器全局对象就会生效。
• 文件级声明：有时，单个 JS/TS 文件顶部会有一行类似 /// 的三斜线指令。这等同于在该文件内单独启用了 DOM 库，效果和修改项目配置一样。

值得一提的是，从 TypeScript 5.0 开始，“lib” 会根据 “module” 和 “target” 设置进行智能推导。但 VSCode 的类型服务有时会缓存旧配置，导致修改后补全列表“纹丝不动”。这时，一个重启 TS 语言服务的操作往往就能立竿见影。

如何精准屏蔽特定全局变量（比如 console 或 process）？

如果只是想屏蔽个别“烦人”的全局变量，比如觉得 console 太常出现，或者在不该出现 process 的环境里看到了它，有没有更精细的控制方法？

答案是肯定的，但思路不是“过滤”，而是“覆盖”。TypeScript 的类型系统支持声明合并，我们可以通过声明一个同名的全局类型，并将其设置为 never，来让它从补全列表中“消失”。

具体操作是，在项目中创建一个类型声明文件（例如 types/global-override.d.ts），并确保它被 tsconfig.json 的 “include” 字段所覆盖。然后写入如下内容：

declare global {
  // 在浏览器环境全局对象中移除 console 和 localStorage
  interface Window {
    console: never;
    localStorage: never;
    sessionStorage: never;
  }
  // 如果想在 Node 环境中隐藏 process，可以尝试（注意：具体接口名可能因版本而异）
  // interface NodeJS.Global {
  //   process: never;
  // }
}

需要特别提醒的是：将属性设为 never 仅仅是在类型层面将其“删除”，它不会影响代码的实际运行。如果你的代码中确实使用了被屏蔽的变量，TypeScript 会报类型错误。因此，这种方法是在“干净的补全”和“类型安全”之间做权衡，使用时需心中有数。

ja vascript.suggest.autoImports 和全局补全有什么关系？

这是一个常见的误解。VSCode 设置中的 ja vascript.suggest.autoImports（或对应的 TypeScript 设置）控制的是模块自动导入功能。例如，当你键入 useState 时，它是否会自动帮你添加 import { useState } from ‘react’; 这行代码。

这个开关完全不影响 setTimeout、window 这类全局变量的补全出现与否。关掉它，只是让来自模块的符号不再自动添加导入语句，全局变量该出现还是会出现的。

真正对补全列表密度有影响的编辑器设置，其实是这几个：

• editor.suggest.showKeywords：关闭后可以隐藏 if、return 等语言关键字，但对于过滤全局变量帮助不大。
• typescript.preferences.includePackageJsonAutoImports：设置为 “off” 可以防止补全列表里混入 package.json 文件中的字段名（如 name、version）。
• 最有效的一招：配置 tsconfig.json 中的 “types” 数组。这个数组默认为空，意味着会引入所有 @types/ 包。如果你明确写上 [“node”, “jest”]，那么就只有这两个包的全局类型会生效。反之，如果你清空它 []，就能屏蔽所有通过 @types 包引入的全局声明。

JS 文件没 tsconfig.json 怎么办？

对于纯 Ja vaScript 项目，情况会稍微复杂一些。VSCode 会通过 JSDoc 注释和内置的库推断来提供类型信息和补全。这时，控制全局补全的来源确实更棘手，但并非无计可施。

以下是两个可行的务实方案：

• 创建最小化 jsconfig.json：在项目根目录创建一个 jsconfig.json 文件，其效果等同于 TypeScript 项目的 tsconfig.json。通过精确指定 “lib”，可以严格限定全局变量的范围。

  {
    “compilerOptions”: {
      “lib”: [“es2020”], // 只使用 ES2020 标准库，彻底排除 DOM、Node.js 等环境
      “types”: [] // 不自动包含任何 @types 包
    }
  }

• 利用新版 VSCode 的辅助功能：VSCode 1.86 及以上版本提供了 “ja vascript.inlayHints.variableTypes.enabled” 设置。将其设为 false 可以关闭变量类型的行内提示（Inlay Hints），这虽然不直接减少补全项，但能减少屏幕上的视觉干扰，让代码更清爽。

说到底，补全过滤的本质是一个类型系统的边界界定问题，而不是编辑器层面的显示开关。最稳健的解决思路，永远是清晰地告诉 TypeScript：“我不需要什么环境”，而不是事后请求编辑器“别显示什么”。一旦调整了 lib 和 types 配置，别忘了重启 VSCode 或执行 Developer: Restart TypeScript Server 命令，让更改立即生效。