使用npm link关联Angular库clan-auth时触发TS2307模块找不到错误

问题背景 #

构建名为clan-auth的Angular通用组件库，从私有npm仓库安装可正常使用，但通过npm link关联后触发Error TS2307: Cannot find module 'clan-auth' or its corresponding type declarations错误。已确认node_modules中依赖已正确安装，库文件修改能同步到对应目录。

库的package.json配置 #

{
    "name": "clan-auth",
    "version": "0.0.1",
    "publishConfig": {
        "registry": "https://privatNPMRepo"
    },
    "peerDependencies": {
        "@angular/common": "^13.3.0",
        "@angular/core": "^13.3.0",
        "ngx-cookie-service": "^13.1.2",
        "angularx-qrcode": "^13.0.6"
    },
    "dependencies": {
        "tslib": "^2.3.0"
    }
}

项目结构 #

- ...
  - libraries (Angular Workspace)
    - projects
      - auth (clan-auth库源码目录)
  - project (目标Angular项目)

已执行的npm link步骤 #

1. 进入.../libraries/projects/auth目录执行npm link
2. 进入.../project目录执行npm link clan-auth

解决方案 #

1. 确保库已完成构建，link编译产物而非源码 #

Angular库需要编译生成TypeScript类型声明和可执行代码，直接link源码目录会导致TS无法识别模块：

• 进入库所在的Angular工作区根目录（.../libraries），执行带监听的构建命令，实时同步修改：

  ng build clan-auth --watch
  

• 构建完成后，切换到dist目录下的库产物文件夹重新link：

  cd .../libraries/dist/auth
  npm link
  # 回到目标项目重新关联
  cd .../project
  npm link clan-auth
  

2. 配置目标项目的TypeScript路径映射 #

修改目标项目的tsconfig.json，在compilerOptions中添加paths字段，明确指定clan-auth的模块路径：

{
  "compilerOptions": {
    // 其他原有配置...
    "paths": {
      "clan-auth": ["./node_modules/clan-auth"]
    }
  }
}

如果直接关联dist产物，也可以直接指向构建后的目录：

"paths": {
  "clan-auth": ["../libraries/dist/auth"]
}

3. 完善库的package.json入口声明 #

确保库的package.json中包含main、module、types字段，指向构建后的正确产物文件（Angular构建通常会自动生成这些字段，若缺失可手动补充）：

{
  "name": "clan-auth",
  "version": "0.0.1",
  "main": "./bundles/clan-auth.umd.js",
  "module": "./fesm2015/clan-auth.js",
  "types": "./clan-auth.d.ts",
  // 其他原有配置...
}

4. 清除缓存并重启开发服务 #

缓存可能导致模块识别异常，执行以下操作：

• 清除目标项目的缓存文件：

  rm -rf node_modules/.cache
  npx tsc --clean
  

• 重启Angular开发服务：

  ng serve --open
  

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