VSCode 通过集成 TypeScript 语言服务支持 JSDoc 类型推断，需规范书写 @param、@returns、@type 等标签，并启用 // @ts-check 或 jsconfig.json 中 "checkJs": true 才能触发类型检查。
VSCode 本身不直接执行类型检查，但它通过集成 TypeScript（或 JS 语言服务）来提供基于 JSDoc 的类型推断、智能提示和轻量级类型校验。关键在于正确书写 JSDoc，并启用相关设置。
JSDoc 注释怎么写才被识别
VSCode（借助 TypeScript 语言服务）能从 JSDoc 中提取类型信息，但格式必须规范：
- 使用 @param 标注函数参数类型，如
/** @param {string} name */ - 用 @returns 或 @return 说明返回值，如
/** @returns {number} 总长度 */ - 用 @type 给变量或属性标注类型，如
/** @type {Date} */ const now = new Date(); - 支持复杂类型：对象字面量
{name: string, age: number}、数组string[]、联合类型string | null、泛型Array<number></number> - 函数类型可写为
/** @type {(x: number) => string} */或更清晰的/** @type {import('./types').Callback} */
让类型检查真正起作用的关键设置
默认 JS 文件不会报类型错误，需主动开启检查：
- 在 JS 文件顶部加
// @ts-check—— 启用当前文件的类型检查（推荐按需开启） - 或在项目根目录建
jsconfig.json，启用全项目检查：{ "compilerOptions": { "checkJs": true } } - 确保 VSCode 工作区启用了 TypeScript 服务：打开命令面板（Ctrl+Shift+P），运行 “TypeScript: Select TypeScript Version” → 选 “Use Workspace Version”（如果装了本地 ts）或 “Use VS Code’s Version”
- 禁用其他可能干扰的插件（如某些旧版 JavaScript 插件）
常见问题与绕过技巧
不是所有 JSDoc 都能被完美解析，遇到提示不准时可尝试：
- 类型别名太长？用 @typedef 提前定义，再在
@type中引用 - 第三方库无类型？加
/// <reference types="lodash"></reference>或在jsconfig.json的types字段中声明 - 某个变量类型推断失败？补上显式
/** @type {...} */注释，比let x = /** @type {...} */ (y)更稳定 - 想临时忽略某行检查？加
// @ts-ignore（慎用，仅调试）
它不是 TypeScript，但足够好用
JSDoc + checkJs 不提供编译、interface 或 enum 等完整 TS 功能，但对纯 JS 项目来说，它提供了接近 TS 的编辑体验：跳转到定义、重命名、错误高亮、自动补全。不需要改后缀、不引入构建步骤，适合渐进式迁移或轻量脚本。
基本上就这些 —— 写对 JSDoc，开对开关，VSCode 就会默默帮你把类型“看”得清清楚楚。
