VSCode 中配置 JSDoc 的核心是正确书写标准 JSDoc 注释并启用 TypeScript 类型推导：需确保 jsconfig.json/tsconfig.json 中 "checkJs": true，删除 // @ts-nocheck，使用 /* / 格式紧贴函数/变量声明，支持 @param、@returns、@type、@typedef 等标签，可手动补全第三方库类型，排查提示失效需检查文件后缀、导出标注及语言服务状态。

在 VSCode 中配置 JSDoc 并不是为了“安装插件”，而是正确书写注释 + 启用 TypeScript 的类型推导能力——VSCode 内置的 JavaScript 支持（基于 TypeScript 语言服务）会自动解析 JSDoc 并生成精准的代码提示。

确保 JS 项目启用类型检查

VSCode 默认对 .js 文件启用轻量级类型检查，但需确认以下两点：

• 项目根目录存在 jsconfig.json（纯 JS 项目）或 tsconfig.json（TS/JS 混合），且其中 "checkJs": true 已开启（jsconfig 示例）：

{ "compilerOptions": { "target": "ES2020", "module": "commonjs", "checkJs": true, "allowJs": true, "skipLibCheck": true, "noEmit": true }, "include": ["**/*.js"], "exclude": ["node_modules"] }

• 文件顶部没有 // @ts-nocheck 这类禁用注释；如有，删掉或改为 // @ts-check（显式启用）

写对 JSDoc 注释格式才能被识别

VSCode 不解析任意中文注释，只识别标准 JSDoc 标签 + 类型语法。关键写法：

• 用 /** */（双星号开头），不是 /* */ 或 //
• 函数前紧贴声明，空行会断开关联：

/** * 计算两个数的和 * @param {number} a 第一个加数 * @param {number} b 第二个加数 * @returns {number} 和 */ function add(a, b) { return a + b; }

• 支持复杂类型：用 @type 给变量/属性标注，例如：
  /** @type {Map} */
  const userMap = new Map();
• 支持 @typedef 定义自定义类型别名，后续可复用：

/** * @typedef {Object} User * @property {number} id * @property {string} name * @property {string} [email] 可选字段 */

/* @type {User[]} / const users = [];

利用 JSDoc 补齐第三方库缺失类型

很多纯 JS 库（如 Lodash、Axios）不自带类型定义，但你可以用 JSDoc “手动补全”：

Json Repair Kit

使用 Node.js 评估修复格式错误的 JSON，自动纠正尾随逗号、单引号、未加引号的键等常见问题，实现文件规范化。

下载

立即学习“Java免费学习笔记（深入）”；

• 给导入对象加 @type：

/** @type {import('axios').AxiosInstance} */
const api = axios.create({ baseURL: '/api' });

• 为无类型模块新建 types.d.js（同目录），写 @typedef + export 声明，VSCode 会自动加载

提示不生效？快速排查这几点

如果写了 JSDoc 却没提示，大概率是以下原因：

• 文件后缀是 .mjs 或 .cjs？VSCode 当前对这类扩展名的 JS 支持不稳定，建议暂用 .js
• JS 文件里用了 export default 但没写 /** @type {...} */？默认导出需显式标注类型才提示准确
• VSCode 状态栏右下角显示 “JavaScript” 而非 “TypeScript”？点击切换为 TypeScript 引擎（会强制启用类型检查）
• 重启 VSCode 或按 Ctrl+Shift+P → “Developer: Restart TS Server” 刷新语言服务

基本上就这些。不需要额外插件，也不用编译，写对注释 + 开启 checkJs，VSCode 就能实时给出接近 TypeScript 的智能提示。