PAYATHON 2026

TypeScript 如何跨目录导入接口而不改变编译输出结构？

数据阿明

可以，将共享接口放入 .d.ts 声明文件

如果 ApiResponse.ts 只包含接口等类型声明，可以将它改为 ApiResponse.d.ts，在客户端用 import type 导入 ApiResponseData。声明文件会参与类型检查，但不会生成对应的 JavaScript，也不会仅因位于客户端目录之外而扩大默认推断的输出根目录。

如果仍引用原来的 .ts 文件，单独将导入语句改为 import type，通常无法同时解决这两个问题。

为什么导入接口后目录结构会变化？

原问题中，客户端原本只输出 foo.js 和 bar.js。导入服务端的 ApiResponse.ts 后，输出目录里多了 pub 和 sys。

这是 TypeScript 未显式设置 rootDir 时可能出现的情况：编译器根据参与编译的非声明输入文件推断公共根目录。导入 pub 之外的 .ts 文件后，公共根目录可能从 pub 上移到它与 sys 的共同父目录。输出到 outDir 时，编译器会保留文件相对于该根目录的路径，于是出现：

res/js/
├── pub/
│   ├── foo.js
│   └── bar.js
└── sys/
    └── ApiResponse.js

接口本身会被擦除，但定义接口的 .ts 文件仍可能产生输出。根据模块配置，它可能生成空文件，或仅包含模块标记的 JavaScript 文件。

由于没有提供实际的 tsconfig.json，具体行为还要结合 rootDir、outDir 和其他编译选项判断。

方案一：直接将纯接口文件改为声明文件

假设 pub 和 sys 是同级目录，且 ApiResponse.ts 只保存类型定义，可以调整为：

pub/
├── tsconfig.json
├── foo.ts
└── bar.ts
sys/
├── tsconfig.json
├── ApiResponse.d.ts
└── index.ts

sys/ApiResponse.d.ts：

export interface ApiResponseData {
  code?: number;
  title: string;
}

这里只展示原问题明确提供的两个字段，其他已有字段应继续保留。

客户端 pub/foo.ts：

import type { ApiResponseData } from '../sys/ApiResponse';

export function getResponseTitle(response: ApiResponseData): string {
  return response.title;
}

导入时需要注意：

  • 导入名称应为 ApiResponseData，与实际导出的接口名称一致。
  • 示例省略了文件扩展名，以避免直接导入 .ts 扩展名带来的配置要求。实际写法仍需符合项目的模块解析规则。

这样，声明文件可用于客户端类型检查，也不会生成 ApiResponse.js。其他编译输入和配置保持原状时，这个接口文件不会引入额外的输出目录层级。

方案二：把共享类型移到公共目录

接口同时供客户端和服务端使用时，可以单独建立类型目录：

pub/
├── tsconfig.json
└── foo.ts
sys/
├── tsconfig.json
└── index.ts
types/
└── ApiResponse.d.ts

客户端和服务端均使用：

import type { ApiResponseData } from '../types/ApiResponse';

这样可以明确该接口是双方共同使用的数据约定。应避免同时保留两份独立的接口定义，以免后续修改时出现字段不一致。

如果原来的 ApiResponse.ts 还包含函数、对象或其他运行时代码，应只把类型部分移入 .d.ts，运行时代码继续留在 .ts 中。声明文件不能承担实际实现。

为什么其他配置不能直接替代这个做法？

import type 只保证导入语句被擦除

下面的写法能明确表示只使用类型：

import type { ApiResponseData } from '../sys/ApiResponse';

但如果解析到的仍是 ApiResponse.ts，该文件仍会进入编译程序，可能参与根目录推断并生成输出。导入语句不进入 JavaScript，并不等于被导入文件不生成 JavaScript。

exclude 不会阻止显式导入

即使在客户端配置中排除 sys，通过 import 引用的文件仍可能被纳入编译。exclude 主要影响通过 include 搜集初始文件的过程，不能隔离已导入的文件。

强制设置 rootDir 可能产生错误

把客户端 rootDir 固定为 pub，或在 pub/tsconfig.json 中设置为 "."，可以明确客户端源文件的根目录。但如果仍导入根目录之外、需要输出的 .ts 文件，编译器可能报告文件不在 rootDir 下。

将共享接口改为 .d.ts 后，可以按项目需要显式设置客户端 rootDir。rootDir 负责输出路径关系，不负责选择哪些文件参与编译。

noEmit 会关闭整个项目的输出

如果客户端还依赖 tsc 生成浏览器所需的 JavaScript，设置 noEmit: true 就不合适，因为它会停止整个客户端项目的文件输出。

另外，共享接口只提供编译期类型检查，不会自动验证服务端返回的 JSON。是否需要运行时数据校验，应由应用的数据可信度和处理要求决定。

备注：内容仅供参考。