为默认导出的纯JS模块添加类型：cipher-collection类型定义遇阻求助

嘿，我完全懂这种给小众npm包写类型定义卡壳的挫败感！针对cipher-collection这个包，我整理了一套实操步骤，帮你搞定类型定义：

1. 先摸清楚模块的真实导出结构 #

写类型定义的第一步，必须搞清楚这个包对外暴露了哪些API。你提到它的src目录有base64.js和helpers，但咱们得确认最终打包后对外输出的是什么。

你可以先在一个临时JS文件里跑个测试：

// 测试CJS导出
const cipher = require('cipher-collection');
console.log('CJS导出内容:', Object.keys(cipher));

// 测试ESM导出（如果支持的话）
import * as cipherEs from 'cipher-collection';
console.log('ESM导出内容:', Object.keys(cipherEs));

这样你就能拿到所有对外可用的方法，比如可能是base64Encode、base64Decode、isBrowser这些，这是写准类型的核心依据。

2. 创建自定义类型定义文件 #

在你的项目根目录下新建@types/cipher-collection/index.d.ts（没有@types文件夹就手动建一个），然后根据刚才查到的导出结构来写类型。

举个例子，假设模块导出了几个基础加密工具函数，类型定义可以这么写：

declare module 'cipher-collection' {
  /**
   * 判断当前环境是否为浏览器
   */
  export function isBrowser(): boolean;

  /**
   * 对输入内容进行Base64编码
   * @param input 要编码的字符串或二进制数据
   * @returns 编码后的Base64字符串
   */
  export function base64Encode(input: string | Uint8Array): string;

  /**
   * 对Base64字符串进行解码
   * @param input 要解码的Base64字符串
   * @returns 解码后的原始内容（字符串或Uint8Array）
   */
  export function base64Decode(input: string): string | Uint8Array;

  // 如果还有其他加密方法（比如MD5、SHA256），照着这个格式补充就行
}

3. 让TypeScript识别你的自定义类型 #

写完类型文件后，得告诉TS去哪里找它，有两种简单的方式：

• 方式一：配置tsconfig.json
  在你的tsconfig.json里的compilerOptions中添加typeRoots，把自定义类型目录加进去：

  {
    "compilerOptions": {
      "typeRoots": ["./@types", "./node_modules/@types"]
    }
  }
  

• 方式二：直接引用类型文件
  在项目的入口TS文件顶部加一行引用注释：

  /// <reference types="cipher-collection" />
  

4. 适配ESM/CJS混合导出的坑 #

有些包会同时支持ESM和CJS导出，如果你遇到导入时的类型不匹配错误，可以调整类型定义的导出方式。比如如果模块是默认导出一个工具对象，那类型定义要改成这样：

declare module 'cipher-collection' {
  interface CipherTools {
    isBrowser(): boolean;
    base64Encode(input: string | Uint8Array): string;
    base64Decode(input: string): string | Uint8Array;
  }

  const cipherCollection: CipherTools;
  export default cipherCollection;
}

这时候导入就要用import cipher from 'cipher-collection';来匹配。

5. 关于参考RxJS类型的小提醒 #

你提到参考了RxJS的实现，但RxJS的类型系统是为链式响应式流设计的，复杂度很高。而cipher-collection是工具类库，咱们不需要照搬那种复杂结构，重点是准确匹配每个函数的入参、返回值，以及是否有重载场景。

比如如果base64Encode同时支持字符串和Buffer，那可以给它加类型重载：

export function base64Encode(input: string): string;
export function base64Encode(input: Uint8Array): string;
export function base64Encode(input: string | Uint8Array): string {
  // 这里不需要写实现，只是类型定义的占位
}

常见问题排查 #

• 如果TS提示“找不到模块'cipher-collection'”，检查@types/cipher-collection的目录结构是否正确，必须是@types下直接放包名文件夹，里面是index.d.ts
• 如果类型不生效，确认tsconfig.json的typeRoots有没有包含./@types，或者有没有在入口文件加引用注释
• 如果函数参数报错，去看源码里的具体实现，确认参数类型、可选参数、默认值这些细节

要是你写完类型定义后想分享给其他开发者，还可以把它提交到DefinitelyTyped仓库，发布成@types/cipher-collection包，这样其他人就能直接用啦！

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