在JavaScript开发过程中，给函数参数设置默认值已经是常见的编码习惯，而配合合适的注解标注默认值，能让代码更易读、更易维护，也能获得更好的开发工具支持。不同的注解方式有不同的适用场景，下面来详细介绍具体的写法和作用。
JSDoc注释标注参数默认值
JSDoc是JavaScript生态中最常用的注释式注解工具，不需要额外的编译步骤，直接通过注释就能为参数默认值提供说明和类型提示。
基础写法
使用@param标签标注参数时，可以在参数名后添加默认值说明，格式为@param {类型} [参数名=默认值] 描述。
/**
* 计算商品总价
* @param {number} [price=10] 商品单价，默认10元
* @param {number} [count=1] 商品数量，默认1件
* @returns {number} 商品总价
*/
function calcTotal(price = 10, count = 1) {
return price * count;
}
复杂类型默认值标注
如果参数是对象或数组类型，默认值比较复杂，可以在注释中补充默认值的详细结构。
/**
* 初始化用户配置
* @param {Object} [config={}] 用户配置对象，默认空对象
* @param {string} [config.name='游客'] 用户名，默认游客
* @param {number} [config.age=0] 用户年龄，默认0
*/
function initUserConfig(config = {}) {
const { name = '游客', age = 0 } = config;
console.log(`用户：${name}，年龄：${age}`);
}
TypeScript类型标注参数默认值
TypeScript作为JavaScript的超集，通过类型系统可以直接标注参数类型和默认值，注解信息会和类型校验结合，提供更严格的开发约束。
基础类型默认值标注
在参数后直接添加默认值，同时配合类型注解，TypeScript会自动推断参数类型，也可以显式声明类型。
// 显式声明参数类型并标注默认值
function formatStr(content: string = '默认文本', length: number = 10): string {
if (content.length > length) {
return content.slice(0, length) + '...';
}
return content;
}
可选参数与默认值结合
TypeScript中可选参数可以和默认值配合使用，标注可选参数时，默认值会自动让参数变为可选。
// 参数加了默认值后，可省略?标记，调用时可不传该参数
function requestApi(url: string, timeout: number = 3000, headers: Record<string, string> = {}) {
console.log(`请求地址：${url}，超时时间：${timeout}ms`);
console.log('请求头：', headers);
}
参数默认值注解的实际作用
给函数参数默认值添加注解，主要有以下几方面的作用：
- 提升代码可读性：其他开发者阅读代码时，不需要查看函数内部逻辑就能知道参数的默认值是什么，减少理解成本。
- 获得更好的IDE提示：主流编辑器如VS Code会读取注解信息，在调用函数时自动提示参数的默认值，避免传参错误。
- 类型校验支持：TypeScript的注解配合默认值，能在编译阶段检查传入参数是否符合类型要求，提前发现错误。
- 方便自动生成文档：JSDoc的注解可以直接被文档生成工具识别，自动生成包含参数默认值说明的API文档。
两种注解方式的适用场景
如果是纯JavaScript项目，不需要引入TypeScript编译流程，优先选择JSDoc注释的方式标注默认值，零成本接入。
如果是TypeScript项目，直接使用TypeScript的类型标注即可，注解信息和类型系统结合更紧密，能提供更全面的校验能力。
如果项目同时需要兼容两种注解，也可以混合使用，JSDoc注释可以作为补充说明，进一步细化默认值的业务含义。
JS注解函数参数默认值TypeScript类型标注JSDoc注释参数默认值作用修改时间：2026-07-15 09:21:28