Angular库次级入口互引用及跨工作区npm link使用问题排查

一、先把LibraryA的次级入口和打包配置弄对 #

要让跨工作区的库能正确识别次级入口，首先得让LibraryA自己打包后能对外暴露这些入口的模块和类型，别只靠本地paths映射。

• 直接在LibraryA的package.json里声明所有次级入口的导出和类型路径：

  {
    "name": "libraryA",
    "version": "0.0.1",
    "exports": {
      ".": "./dist/libraryA/index.js",
      "./featureA1": "./dist/libraryA/featureA1/index.js",
      "./featureA2": "./dist/libraryA/featureA2/index.js"
    },
    "typesVersions": {
      "*": {
        "featureA1": ["./dist/libraryA/featureA1/index.d.ts"],
        "featureA2": ["./dist/libraryA/featureA2/index.d.ts"]
      }
    },
    // 其他原有配置不动...
  }
  

• 检查LibraryA的tsconfig.lib.json，确保编译时能生成所有次级入口的类型文件，并且输出到正确位置：
  确认compilerOptions里有declaration: true，include包含所有次级入口的源码：

  {
    "extends": "./tsconfig.json",
    "compilerOptions": {
      "declaration": true,
      "outDir": "./dist/libraryA"
    },
    "include": ["src/lib/featureA1/**/*", "src/lib/featureA2/**/*"],
    "exclude": ["src/test.ts", "**/*.spec.ts"]
  }
  

• LibraryA内部引用次级入口还是用import { ... } from 'libraryA/featureA1'，本地开发用的paths映射只保留在自己的tsconfig.json里就行，不用带到其他工作区：

  {
    "compilerOptions": {
      "paths": {
        "libraryA/featureA1": ["src/lib/featureA1"],
        "libraryA/featureA2": ["src/lib/featureA2"]
      }
    }
  }
  

• 打包LibraryA：跑ng build libraryA，确保dist/libraryA下每个次级入口都有对应的index.js和index.d.ts文件。

二、给LibraryB配置npm link引用LibraryA #

别在LibraryB里加LibraryA的paths映射，靠npm link的包本身提供的配置来解析模块。

• 在LibraryB根目录执行npm link ../libraryA（假设两个库在同级目录，路径自己调整），确保link成功。
• 把libraryA加到LibraryB的package.json依赖里：

  {
    "dependencies": {
      "libraryA": "0.0.1"
    }
  }
  

• 调整LibraryB的tsconfig.json，让编译器能正确解析npm link包的导出：
  确保compilerOptions里的moduleResolution是node16或nodenext（Angular18默认应该是，没改的话不用动，改了就调回来）：

  {
    "compilerOptions": {
      "moduleResolution": "node16",
      "allowSyntheticDefaultImports": true
    }
  }
  

• 现在跑ng build libraryB，应该不会再报TS2307错误了，因为编译器会通过libraryA的package.json里的exports和typesVersions找到对应的模块和类型。

三、给应用配置npm link引用两个库，解决NG0203错误 #

NG0203一般是因为模块重复加载，或者Angular找不到对应的NgModule，按下面步骤来：

• 先在应用根目录执行npm link ../libraryA和npm link ../libraryB。
• 把两个库加到应用的package.json依赖里：

  {
    "dependencies": {
      "libraryA": "0.0.1",
      "libraryB": "0.0.1"
    }
  }
  

• 关键操作：在应用的angular.json里开preserveSymlinks，避免模块重复加载：
  找到projects.[你的应用名].architect.build.options和serve.options，都加上"preserveSymlinks": true：

  {
    "projects": {
      "your-app-name": {
        "architect": {
          "build": {
            "options": {
              "preserveSymlinks": true,
              // 其他原有配置不动...
            }
          },
          "serve": {
            "options": {
              "preserveSymlinks": true,
              // 其他原有配置不动...
            }
          }
        }
      }
    }
  }
  

  这个配置会让Angular直接用符号链接指向的原始库文件，不会复制一份，避免同一模块被加载多次导致的NG0203错误。
• 应用里导入库的模块时，用正确的次级入口路径，比如import { FeatureA1Module } from 'libraryA/featureA1'，然后在应用的NgModule里导入对应的模块。
• 跑ng serve，应该就能正常运行，不会再出NG0203错误了。

几个要注意的点 #

• 所有库的package.json里的exports和typesVersions必须配置对，这是跨工作区解析次级入口的核心，不用依赖消费端加paths映射。
• Angular18用的是ES模块，moduleResolution设成node16或nodenext才能正确识别exports字段。
• preserveSymlinks是解决NG0203的关键，npm link的符号链接容易导致模块重复加载，开这个选项就能搞定。

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