如何从TypeScript定义文件（.d.ts）中动态加载接口？

这个问题的核心在于TypeScript接口的本质——它们是编译时仅有的类型信息，完全不会出现在编译后的JavaScript代码中，也不会被Node.js或浏览器当作可执行模块加载。这就是为什么你用动态import()加载.d.ts文件会失败的原因：.d.ts文件本身只是给TypeScript编译器做类型检查用的，不会被编译成可执行的JS代码。

下面针对不同需求，给出两种可行的解决方案：

1. 提取接口的名称和结构信息（用于代码生成、文档等场景） #

如果你的需求是获取.d.ts文件中接口的名称、属性名称和类型信息（比如做自动代码生成、文档生成），可以使用TypeScript Compiler API来解析.d.ts文件的抽象语法树（AST），从中提取所需信息。

实现代码示例 #

import * as ts from 'typescript';

async function extractInterfacesFromDts(filePath: string) {
  // 配置编译选项，专注于解析.d.ts文件
  const compilerOptions: ts.CompilerOptions = {
    allowJs: false,
    declaration: true,
    noEmit: true, // 不需要生成编译产物
    target: ts.ScriptTarget.ESNext,
  };

  // 创建Program实例，加载目标.d.ts文件
  const program = ts.createProgram([filePath], compilerOptions);
  const sourceFile = program.getSourceFile(filePath);

  if (!sourceFile) {
    throw new Error(`无法加载目标文件: ${filePath}`);
  }

  // 存储提取到的接口信息
  const interfaces: Record<string, { properties: Record<string, string> }> = {};

  // 遍历AST节点，筛选导出的接口
  ts.forEachChild(sourceFile, (node) => {
    if (
      ts.isInterfaceDeclaration(node) &&
      // 只处理导出的接口
      node.modifiers?.some(mod => mod.kind === ts.SyntaxKind.ExportKeyword)
    ) {
      const interfaceName = node.name.getText();
      interfaces[interfaceName] = { properties: {} };

      // 遍历接口的属性，提取属性名和类型
      node.members.forEach((member) => {
        if (ts.isPropertySignature(member)) {
          const propName = member.name.getText();
          // 获取属性类型的文本描述，比如"string"、"number"
          const propType = member.type?.getText(sourceFile) || 'unknown';
          interfaces[interfaceName].properties[propName] = propType;
        }
      });
    }
  });

  return interfaces;
}

// 使用示例
extractInterfacesFromDts('path/to/your/file.d.ts')
  .then(result => {
    console.log('提取到的接口信息:', result);
    // 输出示例:
    // {
    //   ExampleInterface1: { properties: { id: "string", type: "string" } },
    //   ExampleInterface2: { properties: { id: "string", type: "string" } }
    // }
  })
  .catch(err => console.error('解析.d.ts文件出错:', err));

工作原理 #

TypeScript Compiler API可以直接解析TS/TS声明文件的AST，通过遍历节点识别出interface声明，然后提取名称、属性等信息。这种方式完全在运行时处理，不需要依赖TS编译过程。

2. 运行时类型校验（如果需要用接口约束数据） #

如果你想在运行时对数据进行类型校验，直接用TS接口是做不到的——因为接口编译后就消失了。这时候可以把TS接口转换成运行时可用的Schema（比如JSON Schema、自定义校验函数），然后动态加载这个Schema来校验数据。

实现思路 #

1. 手动或通过工具（比如typescript-json-schema）把.d.ts中的接口转换成JSON Schema文件；
2. 动态加载这个JSON Schema文件；
3. 使用校验库（比如ajv）根据Schema校验数据。

示例流程 #

首先，安装依赖：

npm install typescript-json-schema ajv

然后生成JSON Schema（可以写脚本自动生成）：

// generate-schema.ts
import * as tjs from 'typescript-json-schema';
import fs from 'fs';

// 编译选项
const compilerOptions = {
  strictNullChecks: true,
};

// 创建Schema生成器
const generator = tjs.buildGenerator(['path/to/your/file.d.ts'], compilerOptions);

if (generator) {
  // 生成ExampleInterface1的Schema
  const schema = generator.getSchemaForSymbol('ExampleInterface1');
  fs.writeFileSync('example-schema.json', JSON.stringify(schema, null, 2));
}

之后动态加载Schema并校验数据：

import Ajv from 'ajv';
import fs from 'fs/promises';

async function validateDataAgainstSchema(schemaPath: string, data: unknown) {
  const ajv = new Ajv();
  const schemaContent = await fs.readFile(schemaPath, 'utf-8');
  const schema = JSON.parse(schemaContent);
  const validate = ajv.compile(schema);
  const isValid = validate(data);

  if (!isValid) {
    console.error('数据校验失败:', validate.errors);
  }

  return isValid;
}

// 使用示例
validateDataAgainstSchema('example-schema.json', { id: '123', type: 'test' })
  .then(isValid => console.log('数据是否符合接口:', isValid));

关键总结 #

• 不要试图用import()直接加载.d.ts文件：它不是可执行的JS模块，运行时不存在对应的代码；
• 若需提取接口元信息，用TypeScript Compiler API解析AST；
• 若需运行时类型校验，把接口转换成运行时Schema。

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