发布到NPM的TypeScript Node包编译失败：找不到模块声明文件

我将小型Node包maps-backend-challenge发布至NPM，执行npm run build和npm publish均无异常，但在全新TypeScript React项目中通过yarn add maps-backend-challenge引入并使用导出函数时，出现两个报错：

报错1：模块解析失败 #

ERROR in ./node_modules/maps-backend-challenge/dist/index.js 33:19-40
Module not found: Error: Can't resolve './maps-api' in '/Users/<redacted>/code/fe-maps-search-2/node_modules/maps-backend-challenge/dist'

报错2：类型声明未被识别 #

ERROR in src/App.tsx:4:36
TS7016: Could not find a declaration file for module 'maps-backend-challenge'. '/Users/<redacted>/code/fe-maps-search-2/node_modules/maps-backend-challenge/dist/index.js' implicitly has an 'any' type.
  Try `npm i --save-dev @types/maps-backend-challenge` if it exists or add a new declaration (.d.ts) file containing `declare module 'maps-backend-challenge';`
    2 | import logo from "./logo.svg";
    3 | import "./App.css";
  > 4 | import getAutoCompleteDetails from "maps-backend-challenge";
      |                                    ^^^^^^^^^^^^^^^^^^^^^^^^
    5 |
    6 | function App() {
    7 |   getAutoCompleteDetails();

我认为这两个问题均与模块配置或类型声明相关，已手动添加index.d.ts文件，但仍无法正常编译，希望找到正规解决方式，而非临时补丁。

项目文件结构 #

├── dist
│   ├── index.d.ts
│   ├── index.js
│   ├── maps-api.js
├── LICENSE
├── package.json
├── README.md
├── src
│   ├── index.ts
│   └── maps-api.ts
└── tsconfig.json

现有手动编写的index.d.ts内容 #

// index.d.ts
declare module "maps-backend-challenge" {
  export interface AutoCompleteDetails {
    placeId: string;
    streetName: string;
    streetNumber: string;
    countryCode: string;
    country: string;
    freeformAddress: string;
    municipality: string;
  }

  export function getAutoCompleteDetails(
    address: string,
    countryCode: string
  ): Promise<AutoCompleteDetails[]>;

  export function getPlaceAutocomplete(
    key: string,
    address: string,
    countryCode: string
  ): Promise<any>;
}

正规解决方案 #

1. 修复模块解析失败问题 #

这个错误并非类型问题，而是编译后的模块路径不匹配：

• 检查src/index.ts中导入maps-api的语句，如果是import { ... } from './maps-api'，TypeScript编译后可能保留了无扩展名的路径，但Node/浏览器在解析时需要明确.js后缀。
• 两种修复方式：
  • 推荐方案：在tsconfig.json中设置"moduleResolution": "node16"或"nodenext"，让TypeScript自动处理模块扩展名解析，编译后会自动添加正确的.js后缀。
  • 备选方案：手动在TS文件的导入语句中添加.js后缀（如import { ... } from './maps-api.js'），虽然编写TS时看起来不符合习惯，但编译后的路径是正确的。
• 同时确保tsconfig.json的include包含src/**/*，outDir设为dist，保证编译时所有依赖文件都输出到dist目录。

2. 修复类型声明未被识别问题 #

手动编写的index.d.ts未被识别，核心原因是NPM包未在配置中声明类型文件路径，且手动编写容易和实际代码不一致：

1. 在package.json中添加types字段，指定类型文件位置：

{
  "name": "maps-backend-challenge",
  // ...其他配置
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts" // 新增此行
}

2. 启用TypeScript自动生成类型文件：在tsconfig.json中设置"declaration": true，这样编译TS时会自动生成与代码完全匹配的.d.ts文件，无需手动编写。
3. 删除手动创建的index.d.ts，重新执行npm run build，TypeScript会自动在dist目录生成正确的类型文件。

最终验证步骤 #

1. 更新tsconfig.json配置：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "declaration": true,
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

2. 更新package.json添加types字段（如上所述）。
3. 重新执行npm run build，确认dist目录下生成了自动编译的index.d.ts和maps-api.d.ts。
4. 重新发布包：npm publish，然后在React项目中重新安装maps-backend-challenge测试编译是否正常。

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