TypeScript package.json imports 和自包名导入有什么区别

这两个写法都能让包内文件少写相对路径，但它们不是同一套映射：以 # 开头的字符串查 package.json 的 imports，当前包名开头的字符串查本包 exports。前者适合隐藏内部目录，后者适合让包内代码提前走一遍对外 API 边界。

官方参考：https://www.typescriptlang.org/docs/handbook/modules/reference.html

先看两个导入字符串分别查哪一个字段

假设包名是 @demo/ui，源码目录为 src，发布目录为 dist。下面的配置是合法 JSON，字段旁的含义用正文解释，不把注释塞进配置文件。

{
  "name": "@demo/ui",
  "imports": {
    "#utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.js"
    }
  },
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./utils": {
      "types": "./dist/utils.d.ts",
      "import": "./dist/utils.js"
    }
  }
}

源码中的 import { format } from "#utils" 只会走 imports；import { format } from "@demo/ui/utils" 则走包名自引用和 exports。Node.js 也要求自引用存在 exports，并且只能访问已导出的子路径。

只想隐藏内部目录时使用 imports

imports 的键必须以 # 开头，解析范围是包含当前文件的最近一个 package.json。它适合把 src/utils.ts 抽象成稳定的内部名称，同时不把这个名称暴露给包的使用者。

// 这段源码只依赖包内别名，避免业务文件绑定 src 的层级。
import { format } from "#utils";

export function renderLabel(value: string): string {
  // 让公开函数复用同一份内部实现，发布后由 exports 的产物接管。
  return format(value);
}

在本地项目中，TypeScript 会按照 Node.js 的条件解析 imports，再用 rootDir、outDir 把发布目标反映回源码输入。因此库项目通常应显式设置 rootDir: "./src"，不要让映射悄悄落到上一次构建的旧文件。

要验证公开 API 时使用自包名导入

自包名导入不是普通的 node_modules 查找。编译器先读取最近 package.json 的 name，再按 exports 限制可访问的入口：

// 这个导入故意经过公开子路径，提前暴露 exports 是否完整。
import { format } from "@demo/ui/utils";

export function renderPublicLabel(value: string): string {
  // 如果 utils 没有写进 exports，这里应在开发期就失败，而不是发布后才发现。
  return format(value);
}

这种方式适合组件库、工具包和 monorepo 中的包内自测：内部调用与消费者调用使用同一条公开入口。代价是每个需要被引用的子路径都必须明确写进 exports，不能再依赖“顺手访问包目录下任意文件”。

配置时最容易混淆的三个边界

建议配套使用 moduleResolution: "node16"、"nodenext" 或 "bundler"，并检查 resolvePackageJsonImports 是否被关闭。node10 和 classic 不会提供这套现代 imports/exports 解析。

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "rootDir": "./src",
    "outDir": "./dist",
    "resolvePackageJsonImports": true,
    "resolvePackageJsonExports": true
  }
}

最后做一份发布前检查：先删掉 dist 重建，再确认每个条件目标文件确实会生成；分别搜索 #utils 和 @demo/ui/utils 的解析结果；最后用一个安装后的临时消费者验证 exports。如果只有编辑器能跳转，或者必须额外复制一份 paths 配置才能运行，说明发布契约还没有闭合。

常见问题

imports 能不能写成任意别名？

不能。键必须以 # 开头；普通包名应交给自包名导入或依赖包解析。

自包名导入是不是等同于相对路径？

不是。它受 exports 的公开入口限制，正因为如此才适合提前检查消费者真正能使用的 API。

为什么 TypeScript 能补全，Node.js 却找不到？

常见原因是只配置了 paths，没有同步 package.json 的 imports/exports，或者模块解析模式没有启用 Node.js 包字段。