未指定扩展名导入自定义TypeScript库时出现TS错误

我发布了自定义库my_library，其package.json的exports配置如下：

"exports": {
  ".": {
    "import": "./index.ts"
  },
  "./lib/*": {
    "import": "./lib/*"
  }
},

在应用中安装该库后，执行以下导入代码：

import TextField2 from 'my_library/lib/TextField2'

Vite构建运行正常，但TypeScript抛出错误：

Cannot find module 'my_library/lib/TextField2' or its corresponding type declarations.ts(2307)

添加文件扩展名后，导入可正常工作：

import TextField2 from 'my_library/lib/TextField2.tsx'

另外，my_library的index.ts通过以下代码重新导出该模块：

import TextField2 from "./lib/TextField2";
export { TextField2 };

此时应用中使用import {TextField2} from 'my_library'导入时，TypeScript可正常识别类型，无报错。

调用方的tsconfig.json配置如下：

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": [ "ES2023", "DOM" ],
    "module": "ESNext",
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,

    "allowJs": true,
    "baseUrl": "."
  },
  "include": [ "src" ],
  "references": [ { "path": "./tsconfig.node.json" } ]
}

TypeScript解析package的exports字段时，无法自动推断通配符路径对应的类型文件，尤其是当源文件使用.tsx这类非标准.ts扩展名时。Vite作为构建工具会严格按照exports配置查找实际文件，因此能正常运行，但TypeScript的类型检查系统无法匹配到对应的类型声明文件，从而抛出错误。而通过主入口index.ts导出时，TS能通过主入口的类型关联到子模块类型，因此不会报错。

方案1：为exports添加types字段 #

修改my_library的package.json，在每个exports条目里明确指定类型文件路径：

"exports": {
  ".": {
    "import": "./index.ts",
    "types": "./index.ts"
  },
  "./lib/*": {
    "import": "./lib/*",
    "types": "./lib/*.d.ts"
  }
},

如果你的库未预先生成.d.ts类型声明文件，也可以直接指向.tsx源文件，但更规范的做法是通过tsc生成类型声明文件后再配置。

方案2：配置typesVersions字段 #

在my_library的package.json中添加typesVersions，为通配符路径映射类型文件：

"typesVersions": {
  "*": {
    "lib/*": ["./lib/*"]
  }
}

该配置会告诉TypeScript，当匹配到my_library/lib/*的导入路径时，去库的./lib/*目录下查找对应的类型文件。

方案3：生成完整的类型声明文件 #

在my_library的tsconfig.json中开启类型声明生成：

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./types"
  }
}

然后在package.json中指定类型入口：

"types": "./types/index.d.ts"

同时配合方案1的exports类型配置，确保TypeScript能正确解析所有子路径的类型。

验证 #

修改完成后，重新发布或本地链接库，应用中使用import TextField2 from 'my_library/lib/TextField2'时，TypeScript即可正常识别类型，不再抛出错误。

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