从打包后的JS包导入函数时VSCode IntelliSense失效求助

问题场景 #

用VSCode维护一个NPM包时，本地测试代码里导出函数的IntelliSense能正常显示注释块的参数描述，但用Webpack打包后，不管是本地导入还是从NPM导入bundle，IntelliSense都无法显示文档注释。

提供的Webpack配置如下：

// Function: pack all js files into a single minified .js file.
// pardon the extensive comments. I am a hobbyist.
const path = require('path');

module.exports = 
{
  entry: '../src/PackageTreeEntry.tsx',

  optimization: {
    minimize: true //false //true // human readable if minimize if false
    // NOT ME >>    minimize: false
    // This option enables tree shaking, which removes unused code from the bundle-> 
    // ,usedExports: true,
  },
  mode: 'production', //'development',  // development or production
  // resolve is a fancy way of saying "look here for files to build graph". Extensions says use .js .jsx 
  resolve: { 
    extensions: ['.js', '.jsx', '.ts', '.tsx']
  },
  // setup where to put minified output file "the bundle", and any assets like jpegs. 
  output: {
    // specify bundle location.
    // ../xyz is necessary if client uses local import of bundle; if node_modules is in
    // parent folder, it causes React to mess up due to duplicate react's etc.
    path: path.resolve(__dirname, '../../publicProj/npmjs_com/bundle-publish-public'), 
    filename: 'bundle.js', // name of combined file, the "bundle"
    // https://webpack.js.org/configuration/output/#outputlibrarytype
    // library type 'window' will not create a bundle file. It's for running as a server, or clicking on index.html.
    // I think it means "make library available via the DOM window object"
    // NOT ME >>  library: { name: 'MyLibrary' , type: 'window' } 
    // type: 'commonjs2' works on client but not local serve or clicking on index.html
    library: { type: 'commonjs2' } 
  },
   
  externals: {        
    react: {          
        commonjs: 'react',          
        commonjs2: 'react',          
        amd: 'React',          
        root: 'React',      
    },      
    'react-dom': {          
        commonjs: 'react-dom',          
        commonjs2: 'react-dom',          
        amd: 'ReactDOM',          
        root: 'ReactDOM',      
    },  

    'react-router-dom': {          
      commonjs: 'react-router-dom',          
      commonjs2: 'react-router-dom',           
      // TODO: what are entries for amd and root??  
    },  
  },

  // modules appears to be chunks of processing to do. 
  // In this case, there's 1 module which calls babel to convert jsx in React source to plain js
  module: {
    // jan 2025 typescript added. START of the babel rule
    rules: [  // here's the first rule in the array of rules
      { // START of the babel rule
        test: /\.(js|jsx|ts|tsx)$/,   // feed files *.js and *.js to babel. ref:https://webpack.js.org/configuration/module/#ruletest

        exclude: /node_modules/, // dont send these hundreds of files to babel! Client will download these itself upon "npm i"
        use: {  // ref: https://webpack.js.org/configuration/module/#ruleuse
          loader: 'babel-loader', 

          options: { "presets": ["@babel/preset-typescript", "@babel/preset-env", "@babel/preset-react"] }
        }, 
      },  

      {  // this rule includes .css files
        test: /\.css$/,
        use: [
            { loader: 'style-loader' },
            { loader: 'css-loader' }
        ]
      }

    ]
  },

};

核心原因 #

1. Webpack生产模式下的代码压缩（minimize: true）会移除所有注释，包括用于IntelliSense的JSDoc注释。
2. 项目基于TypeScript，但未生成并发布类型定义文件（.d.ts），VSCode无法通过类型定义获取稳定的文档提示。

具体解决步骤 #

1. 配置Webpack保留JSDoc注释 #

修改optimization配置，指定TerserPlugin保留含JSDoc标签的注释：

const TerserPlugin = require('terser-webpack-plugin');

module.exports = {
  // ...其他原有配置
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        terserOptions: {
          format: {
            // 保留含JSDoc标签的注释
            comments: /^\**!|@preserve|@license|@cc_on|@param|@returns|@description/i,
          },
        },
        extractComments: false, // 不把注释提取到单独文件
      }),
    ],
  },
};

2. 生成并发布TypeScript类型定义 #

通过TypeScript编译器生成类型定义，这是IntelliSense识别文档的更可靠方式：

• 在tsconfig.json中启用类型定义输出：

{
  "compilerOptions": {
    "declaration": true, // 生成.d.ts文件
    "declarationDir": "./dist/types", // 类型定义输出目录
    "emitDeclarationOnly": true, // 只生成类型定义，不编译JS
    // ...其他原有配置
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "test"]
}

• 在package.json中指定类型定义入口：

{
  "types": "./dist/types/PackageTreeEntry.d.ts",
  // ...其他原有字段
}

• 打包流程调整为先运行tsc生成类型定义，再执行Webpack打包。

3. 优化Webpack打包策略 #

避免将类型定义文件打包进bundle，确保类型定义单独发布：

• 在Webpack配置中排除.d.ts文件：

module.exports = {
  // ...其他原有配置
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: [/node_modules/, /\.d\.ts$/], // 排除类型定义文件
        use: {
          loader: 'babel-loader',
          options: { "presets": ["@babel/preset-typescript", "@babel/preset-env", "@babel/preset-react"] }
        },
      },
      // ...其他原有规则
    ]
  }
}

• 发布NPM包时，确保类型定义目录包含在files字段中：

{
  "files": [
    "dist",
    "bundle.js"
  ],
  // ...其他原有字段
}

验证 #

执行打包和发布后，在测试项目中导入你的包，VSCode应能正常显示导出函数的参数描述和注释文档。

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