如何不导入NPM/内置模块时使用JSDoc类型提示？

开发者阿泽

2026-7-29

解决JSDoc引用第三方/内置包无类型提示的问题

问题原因

你之前的写法错误在于，Express的Request、Response等类型并非挂载在默认导出（import("express").default）上，而是属于模块的顶级导出。所以用@typedef {import("express").default} express定义的别名，无法访问到这些顶级类型，自然没有提示。Node内置包（如fs）的类型结构同理。

解决方案

1. 直接导入所需的具体类型

针对Express的路由函数，直接导入Request、Response、NextFunction类型：

/** @typedef {import("express").Request} Request */
/** @typedef {import("express").Response} Response */
/** @typedef {import("express").NextFunction} NextFunction */

/**
 * @param {Request} request
 * @param {Response} response
 * @param {NextFunction} next
 */
function my_router(request, response, next) {
  // 输入request.即可获得完整提示
}

export default my_router;

2. 给整个模块定义类型别名

如果需要频繁引用包内的多个类型，可以给整个模块定义别名，注意要用typeof来获取模块的类型结构：

// 定义一个占位变量，仅用于类型提示，无需实际导入
/** @type {typeof import("express")} */
const express = {};

/**
 * @param {express.Request} request
 * @param {express.Response} response
 * @param {express.NextFunction} next
 */
function my_router(request, response, next) {
}

export default my_router;

3. Node内置包的处理方式

以fs为例，同样直接引用模块的顶级类型即可：

/** @typedef {import("fs").ReadStream} ReadStream */
/** @typedef {import("fs").WriteFileOptions} WriteFileOptions */

/**
 * @param {ReadStream} stream
 */
function handleStream(stream) {
  stream.on('data', (chunk) => {
    // 此处可获得ReadStream的方法/属性提示
  });
}