VSCode中的JSDoc：为你的JS代码自动生成文档注释_网络技术

发布时间 - 2026-01-01 00:00:00 点击率：次

VSCode中可自动补全JSDoc注释：一、用/**回车生成基础模板；二、装Auto Import扩展提升类型推断；三、启用jsdoc.autoAppendClosingTag和formatOnSave确保格式规范；四、用JavaScript Docstring Generator自定义模板。

如果您在vscode中编写javascript代码，希望快速为函数、类或变量添加标准化的jsdoc注释，但手动编写耗时且易出错，则可借助编辑器内置功能与扩展实现自动化补全。以下是实现jsdoc注释自动生成的具体步骤：

本文运行环境：MacBook Air，macOS Sequoia。

一、使用VSCode内置JSDoc快捷键

VSCode原生支持JSDoc模板生成，无需安装额外扩展，适用于函数声明、方法定义等常见场景，其原理是根据光标所在位置的函数签名自动推导参数与返回值类型。

1、将光标置于函数名正上方空行处（如function calculateTotal() { 的上一行）。

2、输入 /** 并按下回车键。

3、VSCode自动展开为完整JSDoc结构，包含 @param 和 @returns 占位符，并依据函数参数列表填充参数名。

当项目中存在类型定义文件（如.d.ts）或ES6模块导入时，基础快捷键可能无法准确识别参数类型。Auto Import扩展能结合TypeScript语言服务，提升JSDoc中@param类型推断的准确性。

1、打开VSCode扩展面板（Ctrl+Shift+X 或 Cmd+Shift+X）。

2、搜索并安装 Auto Import - ES6, TS, JSX, CSS, JSON 扩展。

3、重启VSCode后，在函数上方输入 /** 回车，观察是否自动补全更精确的类型标注（如 @param {number} count）。

默认情况下，VSCode不会自动闭合JSDoc块末尾的 */，也未强制对齐多行注释。启用相关设置可确保生成的注释符合团队规范，避免格式混乱。

1、进入设置界面（Cmd+, 或 Ctrl+,）。

2、搜索 jsdoc.autoAppendClosingTag，将其设为 true。

3、再搜索 editor.formatOnSave，确保该选项已启用。

对于需要统一公司级文档风格（如添加@author、@since、@example）的场景，内置功能无法满足。JavaScript Docstring Generator扩展允许用户自定义JSDoc模板，适配不同项目规范。

1、在扩展市场中安装 JavaScript Docstring Generator。

2、按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows/Linux），输入 Docstring: Configure Template 并回车。

3、在弹出的JSON编辑器中，修改 template 字段，例如添加 "author": "Your Name" 与 "example": ["// example usage"]。