TypeScript package.json exports 怎么让 bundler 模式找到 types 条件

很多包已经把 JavaScript 和声明文件都发布了，但应用一换成 moduleResolution: "bundler"，编辑器却提示找不到类型，或者导入结果退化成 any。问题通常不在 bundler 本身，而在 package.json 的 exports 没有把“类型入口”和“运行时入口”放在同一个条件分支里。

解决思路是：让 bundler 模式使用 import 条件，再在这个对象内部把 types 放在 default 前面。TypeScript 会先尝试声明文件，实际打包仍由 default 指向 JavaScript。本文只讨论这条解析路径，不展开 Node 运行时发布规则。

在 bundler 模式下，exports 不是只写一个 JavaScript 文件路径；它要同时给 TypeScript 一个可解析的 types 条件，并给打包器一个可执行的 default 条件。

官方地址：https://www.typescriptlang.org/docs/handbook/modules/reference.html

先看清 bundler 模式到底匹配什么

moduleResolution 决定 TypeScript 如何解析 import 路径。bundler 模式同时支持传统的 node_modules 查找和较新的 package.json exports。当源文件写的是 ESM import，并且 module 使用 esnext 或 preserve 时，解析器会把这次请求交给 import 条件。

这里容易混淆两个层次：import 是条件分支，types 和 default 是该分支里的结果选择。不要把 types 写成与 import 并列的顶层路径后，就认为它一定能覆盖 bundler 请求。

在 exports 里先写 types，再写 default

下面是一个只为说明解析关系而写的包结构。JSON 必须保持合法，因此代码块不放注释；关键字段的作用紧跟在代码后面说明。

{
  "name": "@demo/format-kit",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/index.d.ts",
        "default": "./dist/index.js"
      }
    }
  }
}

import 表示这组规则服务于 ESM 导入。进入该对象后，TypeScript 会匹配 types，并尝试读取 ./dist/index.d.ts；打包器或运行时则可以继续使用 default 对应的 ./dist/index.js。把 types 放在前面，是为了让条件对象的遍历先命中类型入口。

包内还要真的存在这两个文件，而且路径必须相对于该包的根目录。只写 types 字段而不生成声明文件，或者把文件名写成 index.d.ts 却发布在另一个目录，都会让 TypeScript 找不到可提供类型信息的目标。

如果包还要开放子路径，例如 @demo/format-kit/parse，也必须在 exports 中明确列出对应键。存在 exports 后，未被键或模式匹配的子路径不会因为磁盘上有文件就自动可用。

让 tsconfig 与 exports 使用同一套语义

应用侧的配置至少要把两个选项配套起来。bundler 不能单独搭配任意 module 值，官方规则要求使用 esnext 或 preserve。

{
  "compilerOptions": {
    "module": "preserve",
    "moduleResolution": "bundler",
    "noEmit": true,
    "strict": true
  }
}

preserve 适合让每个 import 或 require 保持原样的工具链；如果项目只输出 ESM，也可以把 module 设为 esnext。关键不是照抄某个值，而是让 TypeScript 对输入语句的判断和 bundler 实际处理方式一致。

可以用一个最小的类型消费代码确认入口是否符合预期。下面的注释只解释示例的关键意图，不把类型导入误当成运行时调用。

import { formatId } from "@demo/format-kit";
import type { FormatOptions } from "@demo/format-kit";

// 运行时代码来自 default 指向的 JavaScript，类型信息来自 types 指向的声明文件。
const options: FormatOptions = { prefix: "item" };
const result = formatId(42, options);

console.log(result); // 真实项目中可替换为组件属性或请求参数。

类型仍为空时，按四个边界排查

第一，检查条件顺序。一个对象里如果把 default 放在 types 前面，解析器可能先得到 JavaScript 文件，最终没有声明信息。第二，检查 types 路径是否指向真实的 .d.ts，不要把源码 .ts 路径当成已发布的类型入口。

第三，确认 module 没有与 bundler 冲突。若项目实际使用 module: commonjs，就不应继续假设它会使用 ESM 的 import 条件。第四，确认导入的是公开子路径，而不是绕过 exports 直接写包内 dist 路径。

结论：把类型入口当成 exports 契约的一部分

这类问题的核心不是再加一层路径别名，而是把包的三件事写清楚：bundler 请求使用哪个条件、TypeScript 从哪里拿声明、运行时从哪里拿 JavaScript。对 bundler 项目，推荐先确认 moduleResolution: "bundler" 与 module: "esnext" 或 "preserve" 配套，再在 exports 的 import 分支中按 types、default 的顺序给出两个目标。

这样做既不会把类型文件当成运行时代码，也不会依赖未公开的包内路径。后续如果要支持 Node 的不同模块格式，应另行设计对应条件；不要把两套运行时规则混在本文这条 bundler 解析路径里。

相关问题

为什么只写顶层 types 字段还不够？

当 TypeScript 读取 exports 时，解析会优先走公开的条件映射；应把类型目标放进实际命中的 import 分支，不能只依赖传统字段。

types 和 default 能指向同一个文件吗？

技术上可以，但如果运行时代码与声明文件分离，分别指向 .d.ts 和 .js 更清楚，也更容易维护包的发布目录。