如何用JSDoc为解构剩余参数添加类型标注以兼容TypeScript？

我之前也踩过这个坑！TypeScript对JSDoc里的对象解构剩余属性的类型标注确实有特殊要求，你之前尝试的@param {...object} [props.rest]之所以报错，是因为JSDoc里的...语法在这里会被TypeScript误解为函数的剩余参数（比如function fn(...args) {}这种），而不是对象解构出来的剩余属性，所以它才会抱怨“剩余参数必须在参数列表最后”——但我们这里根本不是函数的剩余参数，而是对象内部的属性，自然不适用这个语法。

给你两个纯JSDoc的解决方案，都不需要依赖任何外部类型，完全符合你的需求：

方案一：用@typedef定义基础类型+交叉类型 #

先把必填的props类型单独定义出来，再和一个允许任意额外属性的类型交叉，这样既清晰又灵活：

/**
 * @typedef {Object} FooBaseProps
 * @property {string} a - 字符串类型的必填属性
 * @property {number} b - 数字类型的必填属性
 */

/**
 * 示例函数，接受固定属性a、b和任意额外属性
 * @param {FooBaseProps & Record<string, unknown>} props - 包含固定属性和任意额外属性的对象
 */
function Foo({ a, b, ...rest }) {
  // 这里可以正常使用rest里的额外属性
  console.log(rest);
  return `<h1>Hello World!</h1>`;
}

// 现在调用时传入额外属性bar，TypeScript不会报错了
Foo({ a: "foo", b: 5, bar: "baz" });

方案二：直接在@param里写带索引签名的对象类型 #

如果你的场景比较简单，不想单独定义typedef，也可以直接在@param的对象类型里添加索引签名，一步到位：

/**
 * 示例函数，接受固定属性a、b和任意额外属性
 * @param {{ a: string; b: number; [key: string]: unknown }} props
 */
function Foo({ a, b, ...rest }) {
  console.log(rest);
  return `<h1>Hello World!</h1>`;
}

// 同样可以正常传入bar等额外属性
Foo({ a: "foo", b: 5, bar: "baz" });

这两种方案的核心都是明确告诉TypeScript：这个props对象除了a和b，还可以包含任意键名、任意类型（这里用unknown是最安全的，你也可以换成更具体的类型比如string/number等）的额外属性。

之前你遇到的问题本质是混淆了“函数剩余参数”和“对象解构剩余属性”的JSDoc标注方式，现在用上面的方法就能完美解决，而且完全是纯JSDoc实现，不需要依赖任何外部类型定义。

内容来源于stack exchange