TypeScript 中导入原生 Node.js 模块的解决方案

在 TypeScript 项目中，开发者经常会遇到需要导入原生 Node.js 模块（.node 文件）的情况。这类模块通常是用 C++ 编写的 Node.js 扩展，通过 Node.js 的 N-API 或更早的 Native Abstractions 实现。然而，TypeScript 默认情况下无法识别这种特殊模块格式，导致编译时报错。

问题背景

当开发者尝试使用 ESM 语法导入 .node 文件时，TypeScript 会抛出错误，提示找不到模块或其类型声明。这是因为 TypeScript 的类型系统需要明确知道每个导入模块的形状，而原生模块的类型信息需要手动提供。

解决方案

声明模块类型

要为原生模块创建类型声明，可以使用 TypeScript 的模块扩充功能。具体步骤如下：

1. 创建一个类型声明文件（如 bindings.d.ts）
2. 使用通配符模式声明模块路径
3. 定义模块导出的类型

示例代码：

declare module "*/getargv_native.node" {
  const addon: {
    // 这里定义原生模块导出的方法和属性
    getArgv: (pid: number) => string[];
  };
  export default addon;
}

全局类型声明

如果需要在多个文件中共享类型，可以创建全局类型声明：

1. 创建一个全局类型声明文件（如 types.d.ts）
2. 使用 declare global 声明共享类型
3. 在其他类型声明文件中引用这些类型

示例代码：

// types.d.ts
declare global {
  interface GetArgv {
    getArgv(pid: number): string[];
  }
}

// bindings.d.ts
declare module "*/getargv_native.node" {
  const addon: GetArgv;
  export default addon;
}

实际应用

在实际项目中，这种模式可以扩展为更复杂的类型声明。例如，对于包含多个方法的原生模块：

declare module "*.node" {
  interface NativeModule {
    init(): void;
    processData(input: Buffer): Buffer;
    getStats(): { memory: number; calls: number };
  }
  
  const instance: NativeModule;
  export default instance;
}

注意事项

1. 路径匹配：通配符模式 (*/) 可以匹配任意路径中的 .node 文件，但要注意路径的具体匹配规则

2. 类型安全：确保类型声明与实际原生模块的实现一致，否则会导致运行时错误

3. 构建配置：在 tsconfig.json 中确保包含类型声明文件

4. Node.js 版本：不同 Node.js 版本对原生模块的支持可能有所不同，特别是 ESM 支持

通过这种方式，TypeScript 项目可以安全地导入和使用原生 Node.js 模块，同时获得完整的类型检查和智能提示功能。