提升开发体验：基于 JSDoc 的 React 项目自动代码提示方案详解

需求背景

主管和其他同事基于公司的业务特点，开发了一套自研前端框架。技术选型是 React + JavaScript 的组合，上线后表现还不错。现在他们想把这个组件库推广到其他团队使用，所以让我琢磨一下：怎么能让使用者用得更顺手一点？尤其是能不能在写代码的时候有自动提示？

我调研了一下市面上常见的几种方案，大致有以下几类：

• 把整个项目从 JavaScript 重构为 TypeScript，这样就能通过 .ts 或 .tsx 文件自动生成 .d.ts 类型声明文件；
• 不动源码，在外面单独为每个导出的组件手动写 .d.ts 文件；
• 使用 TypeScript 编译器解析 JavaScript 文件，直接生成 .d.ts 文件；对于那些识别不全的部分，再通过 JSDoc 注释来辅助生成更准确的类型信息。

主管的意思是，希望尽可能少投入人力，因为框架已经稳定运行了，不想为了一个“非刚需”的功能去大动干戈。所以最终我们选择了第三种方案——它的最大优点就是：对源码几乎无侵入，改动小，成本低，见效快！

不过它也不是十全十美。比如 TypeScript 自动生成的 .d.ts 文件中，很多函数参数或对象属性都会被推断成 any，即使配合 JSDoc 使用，也并不是所有组件都能有完整的类型提示。有些时候你还是得手动点进 .d.ts 文件里看定义。

但总的来说，瑕不掩瑜。毕竟现在的目标是高效产出，不是追求完美主义。

项目结构说明

我们的框架是一个典型的多包项目，主要由两个核心目录组成：packages 和 components。

packages 目录下包含了四个子包：

• cli：负责创建项目的命令行工具；
• compatible：提供运行环境适配能力；
• multipage：支持多页面应用架构；
• store：实现全局状态管理。

components 目录则主要是 UI 组件和交互能力的集合。

整个项目的目录结构如下所示：

my-project/ ├── components/ │   ├── src/ │   ├── build.config.mts │   └── package.json ├── packages/ │   ├── cli/ │   ├── compatible/ │   │   ├── src/ │   │   ├── build.config.mts │   │   └── package.json │   ├── multipage/ │   └── store/ ├── scripts/   └── package.json 

除了 cli 外，其余子包都需要生成 .d.ts 文件。那我们的思路也很简单：在根目录安装 TypeScript，然后给每个子包加上 tsconfig.json，最后写个脚本批量处理这些子包，自动生成类型声明文件。

安装依赖

因为这些依赖项是多个子包共用的，所以我们统一安装在根目录下：

npm install --save-dev typescript jsdoc @types/react @types/react-dom 

tsconfig.json 配置

每个子包都是独立发布的，所以每个子包都要有自己的 tsconfig.json 文件。
下面是通用配置，利用了 TypeScript 的 emitDeclarationOnly 功能，只用来生成 .d.ts 文件：

{   "compilerOptions": {     "module": "ESNext",     "target": "ES5",     "moduleResolution": "node",     "esModuleInterop": true,     "skipLibCheck": true,     "jsx": "preserve",      "allowJs": true,     "declaration": true,     "emitDeclarationOnly": true,     "outDir": "./types",      "lib": ["es2017", "dom"]   },   "include": ["src/**/*.js", "src/**/*.jsx"],   "exclude": ["node_modules"] } 

自动化脚本编写

为了让这个流程自动化，我们还需要一个脚本，遍历 packages 和 components 文件夹，找到带有 tsconfig.json 的子包，然后执行 TypeScript 命令生成 .d.ts 文件，并放在对应层级下的 types 文件夹中。

我们在 scripts 目录下新建了一个 build-dts.js 脚本，内容如下：

const fs = require("fs"); const path = require("path"); const { execSync } = require("child_process");  const rootDir = __dirname + "/../"; const packagesDir = path.join(rootDir, "packages"); const componentsDir = path.join(rootDir, "components");  function buildDtsForPackage(pkgPath) {   const tsconfigPath = path.join(pkgPath, "tsconfig.json");   const typesOutDir = path.join(pkgPath, "types");    if (!fs.existsSync(tsconfigPath)) {     console.warn(       `⚠️ No tsconfig.json found in ${pkgPath}, skipping .d.ts generation`     );     return;   }    // ---- 清空 types 文件夹 ----   if (fs.existsSync(typesOutDir)) {     console.log(`🧹 Clearing old types folder: ${typesOutDir}`);     fs.rmSync(typesOutDir, { recursive: true, force: true });   }    try {     // 执行 tsc 命令只生成类型声明文件     execSync(`tsc`, {       cwd: pkgPath,       stdio: "inherit",     });      console.log(`✅ .d.ts generated for ${pkgPath}`);   } catch (e) {     console.error(`❌ Failed to generate .d.ts for ${pkgPath}`);   } }  function processDirectory(targetDir) {   if (!fs.existsSync(targetDir)) {     console.warn(`⚠️ Directory not found: ${targetDir}, skipping.`);     return;   }    const dirs = fs.readdirSync(targetDir);    for (const dir of dirs) {     const fullPath = path.join(targetDir, dir);     const stat = fs.statSync(fullPath);     if (stat.isDirectory()) {       buildDtsForPackage(fullPath);     }   } }  function processComponentsFlat(targetDir) {   const tsconfigPath = path.join(targetDir, "tsconfig.json");    if (!fs.existsSync(tsconfigPath)) {     console.warn(`⚠️ components/tsconfig.json not found, skipping.`);     return;   }    console.log(`✅ Building dts for flat components directory: ${targetDir}`);   buildDtsForPackage(targetDir); }  function main() {   console.log("📦 Processing packages directory...");   processDirectory(packagesDir);    console.log("🧩 Processing components directory...");   processComponentsFlat(componentsDir); // 处理扁平的 components 目录 }  main(); 

接着在根目录的 package.json 中加一条脚本指令：

{   "scripts": {      "build:dts": "node scripts/build-dts.js"   }   } 

现在只需要在终端输入：

npm run build:dts 

就能一键为所有子包生成 .d.ts 文件啦！

实际效果展示

在没有改一行源码的情况下，TypeScript 自动生成的 .d.ts 文件长这样：

虽然类型定义可能还不够精准，但已经能帮开发者理解 API 的基本用法了。

但有些组件就比较复杂，TypeScript 推不出来详细的结构，比如下面这个组件生成的 .d.ts 就显得有点鸡肋，根本看不出组件该如何使用：

这时候就可以借助 JSDoc 来补充说明了。

用 JSDoc 补充类型信息

以 Page 组件为例，我们在源码顶部加上 JSDoc 注释，定义 props 结构和生命周期参数：

/**  * @typedef {Object} PageProps  * @property {React.ReactElement} children - 子元素  * @property {(info: PageLifecycleInfo) => void} [onPageBeforeIn] - 页面进入前触发（路由切换时）  * @property {(info: PageLifecycleInfo) => void} [onPageBeforeOut] - 页面离开前触发（路由切换时）  * @property {(info: PageLifecycleInfo) => void} [onPageAfterIn] - 页面进入后触发（DOM挂载完成）  * @property {(info: PageLifecycleInfo) => void} [onPageAfterOut] - 页面离开后触发（DOM卸载前）  * @property {(info: PageLifecycleInfo) => boolean} [onPageBeforeUnmount] - 页面卸载前触发（可阻止卸载）  * @property {(info: PageLifecycleInfo) => void} [onPageAfterUnmount] - 页面卸载后触发  * @private  */  /**  * 页面生命周期信息对象，提供页面相关的上下文数据。  *  * @typedef {Object} PageLifecycleInfo  * @property {string} path - 当前路由路径  * @property {Record<string, any>} params - 路由参数对象  * @property {string} title - 页面标题  * @property {"PUSH" | "REPLACE" | "GO" | "BACK" | "FORWARD" | "LISTEN"} openMode - 路由打开方式  * @property {boolean} hideNav - 是否隐藏导航栏  * @property {boolean} micro - 是否作为微前端子页面  * @property {React.ReactElement} component - 页面组件实例  * @property {React.RefObject<HTMLElement>} pageRef - 页面根元素的 Ref 对象  * @property {PopStateEvent | HashChangeEvent} [event] - 原始路由事件对象  */  /**  * Page 是一个页面级别的容器组件，用于管理页面生命周期和渲染内容。  * @type {React.FC<PageProps>}  */ 

再执行

npm run build:dts 

这会生成的 .d.ts 文件就能清楚地告诉开发者：这个组件到底接受哪些 props。

不过也要注意，并不是所有的 JSDoc 注释生成类型声明之后都能在编译软件上有代码提示。有时候还是会遇到一些限制。

发布到 npm

生成完 .d.ts 文件之后，还要确保它们能随着组件一起发布到 npm 上。这就需要在每个子包的 package.json 中添加如下配置：

{    "files": [     "cjs/**",     "esm/**",     "types/**"   ],   "types": "types/index.d.ts", } 

这样用户在使用组件时，就能看到清晰的类型提示和跳转定义了。

效果对比图

没有代码提示时：

有了代码提示之后：

是不是瞬间感觉开发起来轻松多了？通过这种“低成本+高收益”的方式，我们不仅提升了组件库的易用性，也让团队内外的开发者们写起代码来更顺手、更安心。

如果你对前端工程化有兴趣，或者想了解更多前端相关的内容，欢迎查看我的其他文章，这些内容将持续更新，希望能给你带来更多的灵感和技术分享~