当前位置：首页 > 文章列表 > 文章 > 前端 > 使用JSDoc注释泛型函数时TypeScript报错解析

使用JSDoc注释泛型函数时TypeScript报错解析

2025-09-24 18:45:30 0浏览收藏

在使用 JSDoc 注释 TypeScript 代码时，你是否遇到过泛型函数报错的问题？本文深入解析了为何使用 `@type` 注释泛型函数时，TypeScript 会出现类型不匹配的错误，而使用 `@param` 和 `@return` 却能正常工作。通过具体示例，我们揭示了 TypeScript 对 JSDoc 中泛型类型解析的差异，并提供了使用 `@typedef` 解决此类问题的有效方案。想要避免在使用 JSDoc 注释泛型函数时踩坑，更好地利用 TypeScript 的类型系统，就来阅读本文，学习如何正确地注释泛型函数，提升代码质量和可维护性吧！了解更多关于 TypeScript 和 JSDoc 的最佳实践，请持续关注我们的文章。

使用 JSDoc 注释泛型函数时 TypeScript 报错问题解析

本文深入探讨了在使用 JSDoc 注释泛型函数时，@type 和 @param/@return 表现不同的原因，并提供了使用 @typedef 解决相关问题的方案。通过具体示例和代码片段，帮助开发者理解 TypeScript 如何解析 JSDoc 注释中的泛型类型，并避免在使用过程中可能遇到的错误。

在使用 JSDoc 注释 TypeScript 代码时，我们可能会遇到一些意想不到的问题，尤其是在处理泛型函数时。一个常见的问题是，使用 @type 注释泛型函数时，TypeScript 可能会报错，而使用 @param 和 @return 则可以正常工作。本文将深入探讨这个问题的原因，并提供一些解决方案。

问题描述

考虑以下代码片段：

/**
 * @template X
 * @type {function(X): X}
 */
const identity1 = (x) => x;

/**
 * @template X
 * @type {function(X): X}
 */
const identity2 = (x) => identity1(x);

这段代码在 TypeScript 中会产生以下错误：

Type 'X' is not assignable to type 'X'. Two different types with this name exist, but they are unrelated.
  'X' could be instantiated with an arbitrary type which could be unrelated to 'X'.ts(2719)
graph.mjs(4, 14): This type parameter might need an `extends X` constraint.
const identity1: (arg0: X) => X
@template X
@type — {function(X): X}

然而，如果我们将 @type 替换为 @param 和 @return，代码就可以正常工作：

/**
 * @template X
 * @param {X} x
 * @returns {X}
 */
const identity1 = (x) => x;

/**
 * @template X
 * @type {function(X): X}
 */
const identity2 = (x) => identity1(x);

问题原因

问题的根源在于 TypeScript 如何解析 JSDoc 注释中的类型信息。使用 @type 标签定义的类型的作用域仅限于花括号内部。这意味着 @type {function(X): X} 中的 X 实际上并没有引用到 @template X 定义的泛型类型。TypeScript 无法正确地将 @type 标签中声明的类型与外部的泛型类型参数关联起来。

简单来说，TypeScript 对 @type 标签的处理方式，并不能完全支持从 @type 中提取泛型类型信息。

解决方案

一种解决方案是使用 @typedef 标签。@typedef 允许我们定义更复杂的类型，并且可以正确地处理泛型类型参数。

以下是一个使用 @typedef 的示例：

/**
 * @template X
 * @typedef {X extends number ? [1, 2, 3][X] : never} Successor
 */

/**
 * @template X
 * @typedef {X} Identity
 */

/**
 * @template X
 * @typedef {Identity<Identity<X>>} Identity2
 */

/** @type {Successor<Identity<1>>} */
const x = 2;

在这个例子中，我们首先使用 @template 定义了泛型类型参数 X，然后使用 @typedef 定义了 Successor、Identity 和 Identity2 类型。这些类型可以正确地引用泛型类型参数 X。