JS库JSDoc注释在VS Code悬停不显示、webpack构建产物未包含注释如何解决？

问题根因 #

Webpack 生产模式默认会通过 Terser 插件压缩代码，默认配置下会删除所有非版权声明类的注释，同时你的 Babel 配置未显式开启注释保留，最终导致 JSDoc 标注没有被打包进 dist 产物。VS Code 读取函数提示时仅会解析实际的 JS 文件内容，不会从 source map 中提取注释，因此无法展示悬停提示。

解决步骤 #

• 第一步：配置 Terser 保留 JSDoc 注释
  Webpack 5 生产模式默认内置 Terser 插件，你需要手动修改压缩规则保留 JSDoc 格式的注释，修改 webpack.config.js 如下：
  首先头部引入 Terser 插件：
  const TerserPlugin = require('terser-webpack-plugin');
  然后在 optimization 配置节点下新增 minimizer 配置：

optimization: {
  // 你原有的其他 optimization 配置保持不变，新增以下内容
  minimizer: [
    new TerserPlugin({
      terserOptions: {
        format: {
          // 匹配保留JSDoc相关的注释
          comments: /@param|@returns|@typedef|@template|@extends|@callback/,
        },
      },
      // 禁止将注释单独提取为LICENSE文件
      extractComments: false,
    })
  ],
  // 原有配置...
}

• 第二步：修改 Babel 配置保留注释
  你当前的 babel-loader 未显式配置保留注释，在构建过程中可能会提前删除 JSDoc，修改 babel-loader 配置：

module: {
  rules: [
    {
      test: /\.jsx?$/,
      exclude: /node_modules/,
      use: [
        {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-react'],
            // 新增此行，保留所有注释
            comments: true
          },
        },
      ],
    },
  ],
}

• 第三步（可选更优方案）：生成类型声明文件
  如果你的库是对外发布给其他开发者使用，更规范的方案是额外生成 .d.ts 类型声明文件，将 JSDoc 标注写入类型声明中，这样哪怕生产代码完全压缩去除注释，VS Code 也能从类型声明中读取到对应的类型和注释提示，你可以通过以下方式实现：
  1. 项目根目录新增 tsconfig.json，配置 allowJs: true、declaration: true、emitDeclarationOnly: true、outDir: ./dist/types
  2. 在 package.json 中新增 types: ./dist/types/index.d.ts 字段，指定类型声明入口
  3. 构建时新增执行 tsc 命令生成类型文件

内容的提问来源于stack exchange，提问作者Vaasu Dhand