TypeScript库index.d.ts类型声明在其他TS项目中不生效问题

自定义TypeScript npm库在Vue+TS项目中报「无对应导出成员」类型错误，即使库内自带index.d.ts文件，按以下优先级排查修复：

1. 修正库tsconfig.json的错误配置 #

你当前的tsconfig有两个直接导致类型生成失效的问题：

• typeRoots配置写法错误：该字段只接受类型根目录路径列表，不支持glob通配符写法，你配置的"src/types/**/*"会干扰TS的类型解析逻辑，导致生成的d.ts文件结构异常。
• 若保留paths路径别名配置，TS编译时不会自动将别名替换为消费端可解析的相对路径，最终生成的d.ts文件里会残留@/xxx这类只有你库本地能识别的路径，消费端TS无法解析自然识别不到导出。

修正后的最小可用tsconfig配置如下：

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "esnext",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "strictPropertyInitialization": false,
    "declaration": true,
    "declarationDir": "dist",
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}

如果你必须使用@/*路径别名，需要额外安装开发依赖tsc-alias，并将build脚本修改为tsc && tsc-alias，编译完成后工具会自动替换所有js、d.ts文件中的别名路径为合法相对路径。

2. 修正库package.json的发布配置 #

你当前的package.json有两个会导致类型文件缺失/入口识别错误的问题：

• files字段的glob规则错误："dist/*"只会匹配dist根目录下的文件，dist下子目录里的d.ts声明文件不会被打包进npm包，消费端自然找不到完整类型。
• 缺少ESM入口和通用types字段：部分工具链不认typings字段、也不会默认读取esnext格式的模块入口，需要补全对应字段。

修正后的核心配置如下：

{
  "name": "LIBRARY NAME",
  "version": "1.0.0",
  "main": "dist/index.js",
  "module": "dist/index.js",
  "types": "dist/index.d.ts",
  "typings": "dist/index.d.ts",
  "files": [
    "dist/**/*"
  ],
  "scripts": {
    "build": "tsc"
  },
  "husky": {
    "hooks": {
      "pre-commit": "pretty-quick --staged && concurrently npm:test npm:lint"
    }
  },
  "engines": {
    "node": "^14.15.0",
    "npm": "^6.14.0"
  }
}

3. 构建与验证 #

• 重新执行build命令，打开生成的dist/index.d.ts检查：所有导入路径必须是./xxx格式的相对路径，无@/开头的别名路径，且文件中明确存在你对外导出的所有成员的类型声明。
• 可执行npm pack生成本地测试包，解压后确认包内包含dist目录下所有层级的.js、.d.ts文件，无遗漏。
• 将修复后的包重新安装到Vue项目后，在VS Code中通过命令面板执行「Restart TS Server」重启TS服务，清除旧的类型缓存即可。

4. 极端情况排查 #

如果以上配置修改后仍有报错，检查Vue消费端的tsconfig.json：

• 确认compilerOptions中moduleResolution设置为node
• 不要在exclude中无差别排除所有node_modules依赖，可临时在compilerOptions中加"types": ["你的库名"]指定加载对应类型。

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