使用npm link引入TypeScript类库时模块解析失败问题求助

看起来你遇到的核心问题是模块系统不兼容加上类库打包配置与项目解析逻辑不匹配，结合你提供的tsconfig和声明文件，我来一步步帮你解决：

1. 调整TypeScript编译的模块格式 #

你当前的tsconfig使用了"module": "amd"，但React项目常用的构建工具（Webpack/Vite）对ES Modules（ESNext）或CommonJS的支持更友好，AMD模块需要额外配置才能被正确解析。建议修改tsconfig.json：

{
  "compilerOptions": {
    "target": "ES5",
    "module": "ESNext", // 换成更兼容的ES模块，也可选择CommonJS
    "sourceMap": false,
    "declaration": true,
    "outDir": "dist", // 用outDir替代outFile，生成结构化的文件目录（符合现代包规范）
    "declarationDir": "dist/types" // 单独输出类型定义文件
  },
  "include": ["./src/**/*.ts"]
}

如果坚持要生成单bundle，也可以用"module": "UMD"（同时兼容AMD、CommonJS和浏览器全局变量），但更推荐用outDir生成独立文件结构，方便Tree Shaking和精准导入。

2. 完善类库的package.json配置 #

你的domain.common包需要正确配置入口字段，让Webpack能找到对应的代码和类型定义：
在domain.common的package.json中添加以下内容：

{
  "name": "domain.common",
  "main": "./dist/index.js", // 主入口（如果有统一导出的index.ts）
  "module": "./dist/index.js", // ES模块入口
  "types": "./dist/types/index.d.ts", // 类型定义入口
  "files": [
    "dist" // 指定npm发布/链接时包含的文件目录
  ]
}

如果类库是按模块拆分（比如housing/HouseInformation），确保dist目录下的文件结构和src完全一致，这样导入路径才能对应上。

3. 修正项目中的导入路径 #

之前的import {HouseInformation} from 'housing/HouseInformation'是直接引用模块名称，但Webpack会把这个当成相对路径或npm包名，正确的导入应该基于你的类库包名：

import {HouseInformation} from 'domain.common/housing/HouseInformation'

或者你可以在domain.common的src目录下创建一个index.ts，统一导出所有类：

export * from './housing/HouseInformation';
export * from './BaseEntity';
// ...其他需要导出的类

这样在项目中可以简化导入：

import {HouseInformation} from 'domain.common';

4. 处理npm link后的解析问题 #

使用npm link时，Webpack可能会因为符号链接的特性，无法正确解析类库的依赖或模块。可以在React项目的webpack配置中添加如下处理（如果用Create React App，可以用react-app-rewired修改配置）：

module.exports = {
  resolve: {
    symlinks: false, // 禁用符号链接解析，强制Webpack从node_modules复制文件
    modules: [path.resolve(__dirname, 'node_modules'), 'node_modules'] // 确保解析路径正确
  }
}

另外，务必在domain.common目录下先执行npm run build（编译生成dist目录），再执行npm link，否则链接的是未编译的TS源码，Webpack无法直接处理（除非你的项目额外配置了外部TS文件编译，但不推荐）。

5. 调整声明文件的导出风格 #

你当前的声明文件是每个类单独声明模块（declare module "BaseEntity"），这属于AMD风格的全局模块声明，更适合非模块化场景。改成ES模块风格后，声明文件应该和源码的导出逻辑一致，比如HouseInformation.d.ts应该是：

import { BaseEntity } from '../BaseEntity';
export class HouseInformation extends BaseEntity {
  address: string;
  zipCode: string;
  city: string;
  country: string;
  constructor();
}

这样TypeScript就能通过文件路径正确关联类型，而不是依赖独立的模块名称声明。

按照以上步骤调整后，Webpack应该能正确解析你的类库模块，不会再出现"Module not found"的错误。

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