如何无需发布即可调试/编辑仅含类型声明文件的Angular依赖

一、修正npm link的配置与流程 #

• 先检查本地依赖包的打包配置：
  • 若用ng-packagr打包，确认ng-package.json的dest指向的目录能生成完整JS代码+类型文件，不是仅输出.d.ts。
  • 核对依赖包package.json的main、module、types字段路径，比如main要指向dist/foobar/bundles/foobar.umd.js，module指向dist/foobar/fesm2020/foobar.mjs，types指向dist/foobar/foobar.d.ts。
• 重新执行标准npm link流程：
  1. 在本地依赖包根目录先跑npm run build（确保编译出完整产物），再执行npm link。
  2. 主项目根目录执行npm link foobar（替换成你的依赖包名称）。
  3. 删除主项目的node_modules/.angular/cache，重启ng serve，避免缓存干扰映射逻辑。

二、用本地路径直接替换远程依赖 #

• 修改主项目package.json的依赖项，把版本号换成本地依赖包的绝对/相对路径：

  "dependencies": {
    "foobar": "file:../path/to/your/local/foobar-repo"
  }
  

• 执行npm install，此时node_modules会直接关联本地仓库的编译产物。
• 注意：本地依赖包必须提前编译，每次修改后要重新跑npm run build，主项目没自动更新的话就重启ng serve。

三、调整路径映射解决命名空间/映射异常 #

• 在主项目的tsconfig.json中添加路径映射，强制指向本地依赖的编译产物：

  "compilerOptions": {
    "paths": {
      "foobar": ["../path/to/foobar-repo/dist/foobar"],
      "foobar/*": ["../path/to/foobar-repo/dist/foobar/*"]
    }
  }
  

• 同时在angular.json的build配置里开启preserveSymlinks，避免符号链接导致的文件解析问题：

  "projects": {
    "your-project": {
      "architect": {
        "build": {
          "options": {
            "preserveSymlinks": true
          }
        }
      }
    }
  }
  

四、调试时的额外注意点 #

• 主项目和依赖包的Angular版本不能差异过大，版本不兼容会引发各种运行时错误。
• 若依赖包用了自定义命名空间，主项目导入时要和依赖包的导出路径严格一致，比如依赖包导出export class XYZComponent，主项目就用import { XYZComponent } from 'foobar'，别用相对路径。
• 想实现依赖包修改后的热更新，可以在依赖包目录跑npm run build --watch，修改后自动重新编译，主项目刷新页面就能看到变化。

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