JSDoc可通过类型注解为JavaScript提供静态类型提示，提升代码可读性与IDE智能感知能力。1. 使用@param、@returns等标签标注函数参数与返回值类型；2. 支持对象结构、数组、联合类型等复杂类型描述；3. 通过@typedef定义复用类型；4. 添加// @ts-check或配置jsconfig.json启用类型检查；5. 利用@template实现泛型推断。该方式不改变运行时行为，适合渐进式优化项目类型安全。
JavaScript 本身是动态类型语言，不支持传统意义上的类型注解。但在使用像 TypeScript 或支持 JSDoc 的开发环境（如 VSCode、IDEA）时，可以通过 JSDoc 注解为 JS 提供静态类型提示，实现“动态类型标注”的效果。这种方式不会改变运行时行为，但能提升代码可读性与 IDE 智能提示能力。
JSDoc 类型注解基础语法
在函数或变量前使用 JSDoc 注释块，可以明确参数、返回值的类型：
/** * 计算两数之和 * @param {number} a - 第一个数字 * @param {number} b - 第二个数字 * @returns {number} 和值 */ function add(a, b) { return a + b; }IDE 能根据注解识别 a、b 必须为 number 类型，调用时提供自动补全与错误提示。
支持复杂与动态类型的注解方式
JS 中常处理对象、数组、联合类型等复杂结构，JSDoc 提供多种标签满足需求：
-
@param {Object} 可细化为具体结构：
{ name: string, age: number } -
@param {Array
} 或 @param {string[]} 标注字符串数组 - @param {number | string} 表示参数可以是数字或字符串（联合类型）
- @param {*} value 表示任意类型，适合泛用函数
- @typedef 定义自定义类型，提高复用性
/**
- @typedef {Object} User
- @property {string} name
- @property {number} age
- @property {boolean} active - 是否激活 */
/**
- 更新用户状态
- @param {User} user - 用户对象
- @returns {User} 新用户实例 */ function updateUser(user) { return { ...user, active: true }; }
启用类型检查与工具支持
要在纯 JS 文件中启用类型检查，可在文件顶部添加 // @ts-check，让支持 TS 的编辑器对 JSDoc 类型进行校验：
/**
- @param {string} str */ function greet(str) { console.log("Hello, " + str); }
greet(123); // 编辑器会报错：number 不能赋给 string
也可在项目根目录添加 jsconfig.json 配置文件，统一开启类型检查：
动态类型场景下的灵活处理
某些函数需要根据输入类型返回不同结构（类似多态），可通过联合类型或泛型模拟：
- 使用
@param {object} options并结合属性判断实现逻辑分支 - 用
@template T实现泛型效果（TS 支持）
/**
- @template T
- @param {T} value
- @returns {T} */ function identity(value) { return value; }
const n = identity(100); // 类型推断为 number const s = identity("hello"); // 类型推断为 string
基本上就这些。通过 JSDoc 结合现代开发工具，可以在不引入 TypeScript 编译的前提下，实现接近静态类型的开发体验，尤其适合渐进式迁移或轻量级项目。关键在于规范注解书写，让动态类型更“可预测”。
