如何为名称含@的模块编写TypeScript类型声明？

嘿，我之前也处理过这种带@命名空间的模块类型声明问题，其实思路和普通模块一致，只是要注意模块名的完整写法。下面给你详细拆解几种可行的方案：

1. 快速兜底声明（先解决报错） #

如果只是想让TypeScript不再抛出“找不到模块”的错误，先快速做一个兜底声明就行。注意模块名要完整放在引号里，包括@和斜杠：

// 比如放在 src/types/@absinthe/socket.d.ts
declare module '@absinthe/socket' {
  // 先用any类型兜底，后续再补具体类型
  const AbsintheSocket: any;
  export default AbsintheSocket;
  // 如果有其他导出，也可以用export * from ... 或者单独声明
}

2. 完整类型定义（推荐） #

如果要给模块写具体的类型，就按照它实际的导出结构来定义。比如假设@absinthe/socket导出了create函数和Socket类，你可以这样写：

// src/types/@absinthe/socket.d.ts
declare module '@absinthe/socket' {
  // 先定义需要的接口
  export interface SocketConfig {
    url: string;
    timeout?: number;
  }

  // 定义类类型
  export class Socket {
    constructor(config: SocketConfig);
    send(payload: Record<string, any>): Promise<unknown>;
    disconnect(): void;
  }

  // 导出函数
  export function create(config: SocketConfig): Socket;
}

这样在导入使用时，TypeScript就能自动提示类型校验了：

import { create } from '@absinthe/socket';
const socket = create({ url: 'ws://your-api.com' }); // TS会自动校验参数

3. 处理自定义分支/私有包的情况 #

如果这个包是热门包的自定义分支（比如你fork了原包做了修改），可以这样处理：

• 先找原包的官方类型：比如@absinthe/socket对应的官方类型包是@types/absinthe__socket（注意把斜杠换成双下划线，这是@types包的命名规则）
• 把官方类型文件复制到你的项目本地，然后根据自定义分支的改动调整类型
• 同样用declare module '@absinthe/socket'包裹修改后的类型，这样TypeScript会优先使用你本地的声明，而不是npm上的官方@types包

4. 确保TS能识别你的声明文件 #

最后别忘了在tsconfig.json里配置include，让编译器能找到你的.d.ts文件：

{
  "compilerOptions": {
    // 你的其他编译配置
  },
  "include": [
    "src/**/*",
    "src/types/**/*.d.ts" // 把你的类型声明文件路径加进来
  ]
}

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