Angular项目ng serve时foo-dts模块解析失败及全局类型失效问题

一、本地类型文件场景（未做成npm包） #

1. 修正类型文件写法 #

创建src/types/foo-dts.d.ts，内容如下：

export {}; // 必须添加，将文件标记为TS模块，解决模块解析错误

declare global {
  // 定义全局Window扩展类型
  interface Window {
    FooConfig: {
      apiUrl: string;
      env: string;
      // 其他属性按需添加
    };
  }
}

2. 配置tsconfig.json #

确保baseUrl和paths映射正确，同时包含类型文件：

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "foo-dts": ["src/types/foo-dts.d.ts"] // 路径需与实际文件位置匹配
    },
    // 其他编译选项保持不变
  },
  "include": [
    "src/**/*",
    "src/types/**/*.d.ts" // 确保类型文件被TS编译器识别
  ]
}

3. 导入模块激活全局类型 #

在src/main.ts中导入该模块（无需使用导出内容，仅用于触发类型加载）：

import 'foo-dts';

此时重新执行ng serve，模块解析错误会消失，同时Window.FooConfig的类型也能被正确识别。

二、做成npm包场景 #

1. 包结构与类型文件 #

构建如下包结构：

foo-dts/
├── index.d.ts
└── package.json

index.d.ts内容同本地场景：

export {};

declare global {
  interface Window {
    FooConfig: {
      apiUrl: string;
      env: string;
    };
  }
}

2. 配置package.json #

关键要指定类型入口：

{
  "name": "foo-dts",
  "version": "1.0.0",
  "main": "index.d.ts",
  "types": "index.d.ts", // 告诉TS这是类型入口文件
  "files": ["index.d.ts"],
  "type": "module"
}

3. 项目中使用 #

• 安装包：npm install foo-dts（本地开发可使用npm link）
• 在src/main.ts中导入：

import 'foo-dts';

• 无需额外配置tsconfig paths，Angular会自动识别node_modules中的类型文件。

常见坑排查 #

• 不要在declare module 'foo-dts'块中写全局类型：该语法用于定义模块本身的类型，而非全局扩展，会导致全局类型无法生效。
• 检查Angular的tsconfig.app.json：部分项目中该文件的include可能限制了范围，需确保包含类型文件或node_modules中的类型。
• 清除缓存：若修改后未生效，执行ng serve --delete-output-path清除构建缓存后重启。

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