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<string>} 或 @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 类型进行校验：

千面视频动捕

千面视频动捕是一个AI视频动捕解决方案，专注于将视频中的人体关节二维信息转化为三维模型动作。

27

查看详情

// @ts-check

也可在项目根目录添加 jsconfig.json 配置文件，统一开启类型检查：

{ “compilerOptions”: { “checkJs”: true }, “include”: [“src/**/*”] }

动态类型场景下的灵活处理

某些函数需要根据输入类型返回不同结构（类似多态），可通过联合类型或泛型模拟：

• 使用 @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 编译的前提下，实现接近静态类型的开发体验，尤其适合渐进式迁移或轻量级项目。关键在于规范注解书写，让动态类型更“可预测”。