VSCode原生JS补全失效因依赖TS引擎却缺乏类型信息；需jsconfig.json启用语义分析，JSDoc注入类型，AI插件仅辅助意图补全而非替代。
VSCode 默认的 JavaScript 补全只认语法结构，不理解 arr.map 是数组方法、res.json() 是 Express 响应对象行为——语义化补全必须靠插件或配置主动“教”编辑器这些知识。
为什么原生 JS 补全经常失效
VSCode 自带的 JavaScript 语言服务依赖 TypeScript 的类型推导引擎（tsserver），但对纯 JS 项目默认只做轻量级 AST 分析。没有类型信息时，它无法判断：
-
const user = getUser();返回值是不是有.name属性 -
fetch('/api')后链式调用.then()还是.json() -
document.querySelector('.btn').addEventListener的第二个参数该传什么类型函数
结果就是：输入 . 后弹出一堆无关方法，或者干脆没提示。
jsconfig.json 是语义补全的底层开关
不写 jsconfig.json，VSCode 就当你的项目是“无模块、无路径映射、无类型上下文”的裸 JS 文件集合，补全能力直接砍半。
最小可用配置示例：
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"allowSyntheticDefaultImports": true,
"baseUrl": ".",
"paths": {
"@utils/*": ["src/utils/*"],
"@components/*": ["src/components/*"]
}
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}关键点：
-
baseUrl+paths让import { helper } from '@utils/string'能被正确解析并补全导出项 -
include显式声明作用域，否则 tsserver 可能跳过深层目录里的文件 - 即使不用 TypeScript，这个文件也必须存在且路径正确，否则 JSDoc 类型注释也会失效
JSDoc 注释比类型定义更轻量但效果直接
在变量/函数前加 /** @type {...} */ 是最快速注入语义的方式，不需要改构建流程。
常见有效写法：
-
/** @type {HTMLButtonElement} */ const btn = document.getElementById('submit');→ 输入btn.后精准提示click()、disabled等 -
/** @param {string} id @returns {Promise<User>} */ async function fetchUser(id) { ... }→ 调用处fetchUser('123').then(会提示user参数类型 -
/** @typedef {{ name: string; age: number }} User */配合/** @type {User} */实现自定义结构补全
注意：JSDoc 必须紧贴声明行，空行或注释错位会导致类型丢失；@type 中的尖括号要用 < 和 > 转义，否则会被 HTML 解析器截断。
通义灵码、Copilot 这类 AI 插件补的是“意图”，不是“符号”
它们不依赖 AST 或类型系统，而是通过上下文窗口理解你正在写的逻辑。比如：
- 光标停在
function formatDate(date) {后，输入// 返回 YYYY-MM-DD 格式，AI 插件立刻补全return date.toISOString().slice(0, 10); - 在 React 组件里写
const [count, setCount] = useState(0);后，输入// 点击加 1，自动补全<button onClick={() => setCount(c => c + 1)}>
但这类补全有明显边界：
- 不保证类型安全（可能返回
string而非number） - 跨文件调用时若上下文窗口未包含依赖文件，建议会失准
- 对第三方库 API 的掌握依赖训练数据时效性，比如新发布的
zod@4.0方法可能未覆盖
真正稳定的语义补全，永远建立在 jsconfig.json + JSDoc + 语言服务插件的三层基础上；AI 插件只是加速器，不是替代品。
