发布TypeScript包后导入需指定src？问题排查与解决

核心原因 #

直接导入包名时，Node.js和TypeScript会读取包根目录package.json的入口配置，若未正确指定编译产物路径、类型声明路径，就会触发“找不到模块/类型”错误。而导入src是直接读取源码，并非发布包的标准用法。

具体解决步骤 #

1. 修正TypeScript编译配置 #

检查你的tsconfig.json，确保编译产物和类型声明输出到指定目录（比如dist）：

{
  "compilerOptions": {
    "outDir": "./dist",          // 编译后JS文件输出目录
    "declaration": true,         // 开启类型声明文件生成
    "declarationDir": "./dist",  // 类型声明文件输出目录
    "module": "CommonJS",        // 按需选择CommonJS/ESNext
    "target": "ES6",
    "rootDir": "./src"           // 源码根目录
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

执行tsc命令，确认dist目录下生成了.js和.d.ts文件。

2. 配置package.json入口字段 #

在包根目录的package.json中添加以下关键配置，明确包的入口位置：

{
  "name": "@whiterook6/my-package",
  "main": "./dist/index.js",     // CommonJS模块入口
  "module": "./dist/index.mjs",  // ES模块入口（可选，按需添加）
  "types": "./dist/index.d.ts",  // 类型声明文件入口
  "files": ["dist"]              // 指定发布到NPM的文件目录，仅包含编译产物
}

注意：若你的入口文件不是index.ts，需对应修改路径（比如main.ts对应dist/main.js）。

3. 重新发布包 #

• 若需更新版本，先修改package.json的version字段
• 重新编译：tsc
• 发布包：npm publish --access public（scoped包需加--access public）

4. 测试验证 #

在测试项目中删除node_modules和package-lock.json，重新安装包：npm install @whiterook6/my-package，之后直接导入：

import { 你的导出内容 } from "@whiterook6/my-package";

此时应能正常识别模块和类型。

额外注意事项 #

• 不要将src目录发布到NPM，既冗余又可能导致用户依赖未编译的源码，引发兼容问题
• 必须确保tsconfig.json的declaration设为true，否则不会生成类型声明文件，TypeScript项目仍会报错
• 若使用ES模块，需在package.json中添加"type": "module"，同时将tsconfig.json的module设为ESNext

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