声明文件

是什么，为什么存在

声明文件是 JavaScript API 的静态外形。它记录模块导出的函数、类、常量和类型，或者记录宿主环境提供的全局名称。TypeScript 检查使用方时读取这些信息，但输出 JavaScript 时不会把声明变成值；这属于 类型擦除（type erasure） 。

这条边界很重要。declare function charge(): Receipt 的意思是“运行时别处已有这个函数”，而不是“请生成这个函数”。声明可以让编辑器补全和编译器检查变得准确，也可以用一份写错的契约让整个项目产生错误信心。

你会在三类位置遇到声明文件。JavaScript 包可以随包发布自己的类型；没有内置类型的包可以由 @types 包补充；应用也可以用本地声明描述构建工具注入的全局值或非代码资源。用 TypeScript 写库时，通常不应手写整份公开声明，而应让编译器从源码生成。

声明文件不验证网络响应、配置文件或任意 JavaScript 值。外部数据仍应先以 unknown 进入运行时验证，再获得领域类型。声明解决的是“检查器如何理解现有 API”，不是“这个值在运行时是否可信”。

对使用方来说，目标是找到与依赖版本匹配的声明并确认解析结果。对库作者来说，目标是发布一份可由消费者路径访问、并且与每个运行时入口一致的契约。

工作原理

TypeScript 同时处理两个相互关联的图：运行时模块图决定 JavaScript 会加载什么，类型图决定检查器看到什么。声明文件位于类型图中，却必须忠实描述运行时图。导出名称、默认导出、调用方式和模块格式中任何一项不一致，都会让编译通过的代码在加载或调用时失败。

图中的两条路径必须在使用方汇合。检查器找到 formatInvoice 并不证明运行时加载器也能从同一模块取得这个名称。测试声明时既要运行 tsc，也要执行至少一个真实导入。

声明与实现的边界

环境声明（ambient declaration） 告诉检查器某个实体由其他代码提供。declare 后的变量不能带普通初始化器，函数不能带函数体，因为这两种写法都会越过“只描述、不实现”的边界。在 .d.ts 文件中，顶层声明本身就处于环境上下文，许多位置无需重复写 declare。

声明应描述使用方能够观察到的公开表面，而不是复制实现细节。未导出的辅助函数、缓存结构和私有局部变量不属于契约。返回对象是否只读、参数能否省略、函数是否会返回 undefined，则会改变使用方式，必须准确表达。

类型精确度不能高于运行时事实。如果 JavaScript 接受字符串或数字，就不能只声明字符串；如果函数可能找不到结果，就不能去掉 undefined。过宽的 any 会丢掉错误，过窄的签名则会拒绝合法调用，两者都是声明缺陷。

脚本、模块与全局作用域

声明文件没有顶层 import 或 export 时，顶层名称会进入全局作用域。这适合确实由脚本标签或宿主注入的传统全局 API，却很容易污染应用中每个文件的名称空间。现代包通常应该是模块声明文件，并从顶层显式导出公开成员。

任意顶层 import 或 export 都会让文件成为模块。需要从模块文件补充全局名称时，先用 export {} 建立模块边界，再把补充项放入 declare global {}。这样可以看出哪些内容有意进入全局范围。

字符串形式的 declare module "package-name" 可以描述没有类型的外部模块。在已经解析到某个模块的文件中，相似语法也可用于模块增强；后者只扩展现有声明，不能替换默认导出或凭空实现运行时成员。模块增强的完整规则属于相邻主题。

声明合并只发生在允许合并的声明种类上。把两个同名 interface 放进同一作用域可能合并成员，但 type 别名不会这样做。不要依赖偶然的全局合并来拼接包 API；让文件与模块所有权保持明确。

编译器如何找到声明

对相对导入，TypeScript 会按照当前 moduleResolution 模式模拟宿主的查找方式，再通过扩展名替换寻找 .ts 或对应声明文件。例如，运行时目标是 ./invoice-tools.js 时，检查器可以读取同位置的 invoice-tools.d.ts。这不会改变发给运行时的模块说明符。

对包导入，package.json 的 exports、types、模块格式和解析模式共同决定结果。没有读取 exports 时，包根的 types 字段是明确的声明入口；存在 exports 时，每个公开子路径也应映射到与其运行时目标相符的类型。不能只给包根加一份 index.d.ts，却遗漏已经导出的子路径。

可见的 node_modules/@types 包可以提供全局类型和包声明。compilerOptions.types 限制哪些 @types 包进入全局作用域，typeRoots 则改变作为类型包根目录的位置；两者都不应该被当成普通路径别名。遇到解析问题时，用 tsc --traceResolution 查看实际候选路径，不要凭一份固定“查找顺序”猜测。

解析成功只说明检查器找到了一份声明。它不说明该声明与当前 JavaScript 版本匹配，也不说明运行时能加载同一入口。包升级、条件导出和双 ESM／CommonJS 发布都需要契约测试覆盖。

示例

下面四个示例沿着同一条工作流展开：先给现有 JavaScript 模块补类型，再声明一个真实全局值，然后从 TypeScript 源码生成声明，最后用类型测试防止契约漂移。示例中的实现与声明是同一个小型工作区内的文件。

为 JavaScript 模块手写声明

旧模块已经在运行时导出 currency 和 formatInvoice。实现保留在 JavaScript 中；声明文件只记录调用者可见的形状。

声明中的导出名称与 JavaScript 完全一致，使用方也保留 .js 模块说明符。Invoice 只存在于类型层，因此用 import type 表达这一点。currency 则是运行时值，不能只按类型导入。

字面量类型 "EUR" 来自真实常量，而不是作者的愿望。如果实现以后允许配置货币，声明也应改为更宽的类型。反过来，声明增加一个 JavaScript 没有导出的函数，也不会让该函数在运行时出现。

声明宿主提供的全局值

有些构建系统会在应用启动前提供构建信息。本地声明让业务代码知道其形状，但示例仍显式安装运行时值，避免把声明误当成实现。

export {};

declare global {
  var BUILD_INFO: Readonly<{
    version: string;
    channel: "stable" | "canary";
    builtAt: string;
  }>;
}

/// <reference path="./globals.d.ts" />

globalThis.BUILD_INFO = Object.freeze({
  version: "6.2.0",
  channel: "stable",
  builtAt: "2026-09-04T08:30:00Z",
});

const label = `${BUILD_INFO.version} (${BUILD_INFO.channel})`;
console.log(label);
console.log(BUILD_INFO.builtAt);

6.2.0 (stable)
2026-09-04T08:30:00Z

export {} 阻止 Readonly 之外的辅助名称意外进入全局范围，declare global 则明确打开需要补充的部分。这里使用 var 是因为全局 var 声明会对应 globalThis 的属性；这不是鼓励在应用逻辑中随意使用可变全局状态。

测试环境、服务端渲染和命令行脚本也必须安装同样的值，或者在启动时检查它是否存在。声明不能替代这一步。若该数据可以通过普通模块导入，模块通常比全局名称更容易追踪和测试。

从类型化源码生成声明

库源码已经是 TypeScript 时，让编译器生成声明可以减少重复维护。下面的模块同时包含公开接口、常量和函数；运行代码验证行为，随后单独检查声明输出。

export interface InventoryItem {
  readonly sku: string;
  readonly available: number;
}

export const inventoryVersion = 3 as const;

export function stockLabel(item: InventoryItem): string {
  const state = item.available > 0 ? "in stock" : "back order";
  return `${item.sku}: ${state}`;
}

const sample: InventoryItem = {
  sku: "KB-87",
  available: 12,
};

console.log(stockLabel(sample));

KB-87: in stock

npx tsc inventory.ts \
  --declaration --emitDeclarationOnly \
  --module nodenext --moduleResolution nodenext \
  --target es2022 --outDir dist
sed -n '1,80p' dist/inventory.d.ts

export interface InventoryItem {
    readonly sku: string;
    readonly available: number;
}
export declare const inventoryVersion: 3;
export declare function stockLabel(item: InventoryItem): string;

declaration 启用 声明输出（declaration emit） ，emitDeclarationOnly 则不输出 JavaScript。若另一个工具负责转译 JavaScript，这组配置很合适；若 tsc 同时负责运行时代码，就不能只输出声明。

生成结果保留公开签名，丢掉函数体和示例调用。inventoryVersion 保留字面量 3，因为源码用 as const 固定了公开值。每次发布前都应检查生成产物是否包含在包中，不能只在本地生成后被 .gitignore 或打包白名单漏掉。

用类型测试锁定契约

运行测试只能证明 JavaScript 对少量输入的行为，类型测试还要证明合法调用被接受、非法调用被拒绝。@ts-expect-error 比 @ts-ignore 更适合负向用例，因为预期错误消失时，测试本身会失败。

import {
  formatInvoice,
  type Invoice,
} from "./invoice-tools.js";

const valid: Invoice = { id: "INV-105", total: 21.5 };

if (false) {
  // @ts-expect-error total 必须是 number。
  formatInvoice({ id: "INV-106", total: "21.5" });

  // @ts-expect-error id 是必填字段。
  formatInvoice({ total: 21.5 });
}

console.log(formatInvoice(valid));

INV-105: EUR 21.50

这个文件需要先用 tsc --noEmit 检查，再执行成功路径。只用 tsx 运行并不足够，因为它转译并执行代码，却不替代完整类型检查。测试还应从安装后的包入口导入，而不是绕过 exports 直接读取源码。

负向测试应对应真实契约，不要为了提高数量而罗列随意错误。包支持多个子路径或两种模块格式时，每个公开入口至少需要一次成功导入；容易漂移的重载、泛型推断和可选属性则需要针对性用例。

陷阱

手写 .d.ts 不会与 JavaScript 自动同步。修复方法： 能生成就从发布源码生成；必须手写时，同时运行真实导入测试，并把返回值、异常、可选成员和异步行为逐项与实现对照。

这种错误在单个项目中可能安静通过，到另一个依赖组合中才出现重复或被扩宽的成员。修复方法： 模块型声明使用顶层 export；确实需要补充全局时使用 export {} 加 declare global，并保持补充面最小。

占位声明适合极短的迁移接缝，不适合发布契约。修复方法： 从实际使用的最小 API 开始写精确签名，让未知数据保持 unknown，再随着覆盖面扩大补充成员；不要声称尚未检查的 API 已有类型。

该选项跳过声明文件内部的完整检查，主要用于处理依赖图中的重复或不一致类型；它不会验证声明与 JavaScript 是否一致。修复方法： 发布库时单独检查自己的声明和类型测试，并追踪被跳过的上游问题，不能用一个全局开关替代修复。

典型结果是编辑器接受命名导入，Node 却只得到默认值，或者某个 exports 子路径在检查时存在、运行时不可达。修复方法： 从打包后的临时安装目录分别测试 ESM 和 CommonJS 入口；让 .d.mts、.d.cts 或受包 type 约束的 .d.ts 与对应 JavaScript 格式一致。

延伸阅读

• TypeScript 手册：声明文件简介
• TypeScript 手册：模块声明模板
• TypeScript 手册：全局声明模板
• TypeScript 手册：模块解析参考
• TypeScript TSConfig：declaration