Angular项目集成ngx-spinner时遭遇TS2344类型兼容错误

错误详情 #

在Angular项目中集成ngx-spinner时，遇到TypeScript类型错误，报错指向ngx-spinner-component.d.ts文件中的组件声明代码：

ngOnDestroy(): void; static ɵfac: i0.ɵɵFactoryDeclaration<NgxSpinnerComponent, [null, null, null, { optional: true; }]>; static ɵcmp: i0.ɵɵComponentDeclaration<NgxSpinnerComponent, "ngx-spinner", never, { "bdColor": { "alias": "bdColor"; "required": false; }; "size": { "alias": "size"; "required": false; }; "color": { "alias": "color"; "required": false; }; "type": { "alias": "type"; "required": false; }; "fullScreen": { "alias": "fullScreen"; "required": false; }; "name": { "alias": "name"; "required": false; }; "zIndex": { "alias": "zIndex"; "required": false; }; "template": { "alias": "template"; "required": false; }; "showSpinner": { "alias": "showSpinner"; "required": false; }; "disableAnimation": { "alias": "disableAnimation"; "required": false; }; }, {}, never, ["*"], false, never>; }

服务中调用spinner的代码：

busy() {
  this.busyRequestCount++;
  this.spinnerService.show(undefined, {
    bdColor: 'rgba(255, 255, 255, 0.7)',
    color: '#333333',
    type: 'timer',
  });
}

具体错误信息：

error TS2344: Type '{ bdColor: { alias: "bdColor"; required: false; }; size: { alias: "size"; required: false; }; color: { alias: "color"; required: false; }; type: { alias: "type"; required: false; }; fullScreen: { alias: "fullScreen"; required: false; }; ... 4 more ...; disableAnimation: { ...; }; }' does not satisfy the constraint '{ [key: string]: string; }'.
Property '"bdColor"' is incompatible with index signature.
Type '{ alias: "bdColor"; required: false; }' is not assignable to type 'string'.

问题原因 #

这个错误本质是ngx-spinner的类型定义与当前Angular版本不兼容：ngx-spinner的.d.ts文件中，组件输入属性的声明格式不符合当前TypeScript/Angular对组件元数据的类型约束，导致类型检查失败。通常是因为安装的ngx-spinner版本与项目Angular版本不匹配，或者依赖安装时类型定义文件损坏。

解决方法 #

1. 匹配ngx-spinner与Angular版本 #

ngx-spinner的版本与Angular版本强绑定，必须安装对应版本的包：

• Angular 16+ → ngx-spinner@16.x.x
• Angular 15 → ngx-spinner@15.x.x
• Angular 14 → ngx-spinner@14.x.x
• 以此类推（可查看ngx-spinner版本说明确认对应关系）

执行以下命令重新安装适配版本：

# 卸载现有版本
npm uninstall ngx-spinner
# 安装对应版本，比如Angular 16就装16.x
npm install ngx-spinner@16.0.2

2. 清理并重新安装依赖 #

如果是依赖缓存或类型定义文件损坏导致的问题，执行以下步骤重置依赖：

# 删除node_modules和锁定文件
rm -rf node_modules package-lock.json
# 重新安装依赖
npm install

若使用yarn则替换为：

rm -rf node_modules yarn.lock
yarn install

3. 临时跳过库类型检查（不推荐） #

如果需要紧急绕过错误，可修改tsconfig.json文件，开启skipLibCheck跳过对第三方库的类型检查：

{
  "compilerOptions": {
    "skipLibCheck": true,
    // 其他配置...
  }
}

注意：此方法会忽略所有库的类型错误，可能隐藏其他潜在问题，仅作为临时方案使用。

内容的提问来源于stack exchange，提问作者Антон Олег