自定义NPM包运行正常但WebStorm导入时提示无法解析符号的问题排查

• 运行时正常、IDE标红的核心差异是：项目实际运行时依赖的构建工具（Vite/Webpack/ts-node等）会自动处理CommonJS与ES Module的规范互操作，完成转译打通两种模块的导出逻辑，但WebStorm的静态代码解析不会做这类动态适配，完全严格按照包的配置文件做符号索引。
• 未配置package.json的exports路径映射时，IDE和Node.js都不会默认将包内的src/源码目录作为可导入的公开路径，因此直接写import APIRequest from "nsfw-connector/src/APIRequest"的写法会被判定为非法路径。
• 跨规范导出时，module.exports里取require('./XXX').default的写法属于动态取值逻辑，静态解析阶段IDE无法顺着这个逻辑追溯到源码里实际的类定义，因此会报「无法解析符号」，自动导入时也因为找不到对应的符号锚点，生成错误的导入路径。

• 统一包的模块规范，消除解析歧义
  • 在package.json中补充"type": "module"字段，将整个包切换为ES Module规范，避免混用CommonJS与ESM写法带来的索引混乱；如果保留CommonJS入口写法，至少要显式声明"main": "./index.js"作为包入口，不要依赖IDE自动猜测入口位置。
• 配置exports字段做路径映射
  在package.json的exports字段中显式声明所有开放的导入路径，既符合Node.js的现代包规范，也能让IDE正确识别子路径导入的合法性：

  {
    "exports": {
      ".": "./index.js",
      "./src/*": "./src/*"
    }
  }
  

  配置完成后，nsfw-connector/src/APIRequest这类直接指向源码的导入写法就能被正常识别。
• 替换跨规范的兼容导出写法
  把index.js里的CommonJS导出逻辑改成显式的ESM导出转发，让IDE可以直接顺着导入链路追溯到源码定义：

  // 替换原来的 module.exports 写法
  export { default as APIRequest } from './src/APIRequest.js'
  

  这种显式重导出的写法没有动态取值逻辑，静态解析时可以直接关联到对应类的位置，消除「无法解析符号」的报错。
• 补充轻量类型声明
  哪怕是纯JS开发的包，也可以在根目录新增index.d.ts文件，声明所有导出的符号类型，WebStorm会优先识别类型声明文件的索引内容，自动导入时就会生成正确的路径，不会再出现路径错误的问题：

  // index.d.ts 示例
  export class APIRequest {
    // 仅需要声明类结构，不需要写具体实现
  }
  

• 刷新IDE索引缓存
  所有配置修改完成后，在WebStorm的Node.js设置面板中手动触发node_modules的索引刷新，避免旧的缓存导致新配置不生效。

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