如何扩展含@、/特殊字符的外部TypeScript库接口？

问题分析 #

你尝试的两种方案均存在问题：

• 第一种用global命名空间包裹带特殊字符的模块名，TypeScript不支持该语法，因此触发标识符错误。
• 第二种直接声明模块但未遵循模块合并的正确规则，导致TypeScript判定你重新定义了整个模块，覆盖了原有导出内容，进而出现找不到factories等成员的报错。

正确实现步骤 #

1. 创建或修改类型扩展文件，比如src/types/strapi-extensions.d.ts
2. 按以下格式编写代码：

// 定义WebhookStore的具体类型，建议贴合实际API而非用any
type WebhookStore = {
  findWebhooks: () => Promise<Array<{ id: string; name: string; url: string }>>;
  // 可根据实际需求补充更多方法或属性
};

// 模块增强：针对@strapi/strapi进行类型扩展
declare module '@strapi/strapi' {
  export interface Strapi {
    webhookStore: WebhookStore;
  }
}

// 关键：将文件标记为ES模块，触发TypeScript的模块合并逻辑，避免覆盖原有模块
export {};

核心注意事项 #

• 必须添加export {}：这会把.d.ts文件标记为ES模块而非全局脚本，TypeScript才会将你的扩展声明与原有@strapi/strapi的模块声明合并，而非覆盖。
• 类型定义尽量精准：不要用any兜底，根据webhookStore的实际API定义类型，提升代码的类型安全性。
• 确保TypeScript识别类型文件：检查tsconfig.json的include数组是否覆盖了你的类型文件路径，示例配置：

{
  "include": ["src/**/*", "src/types/**/*.d.ts"]
}

验证效果 #

完成配置后，即可正常使用扩展后的strapi.webhookStore，同时不会丢失原有模块的导出内容：

import { Strapi } from '@strapi/strapi';

async function fetchWebhooks(strapi: Strapi) {
  const webhooks = await strapi.webhookStore.findWebhooks();
  console.log(webhooks);
}

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