理解TypeScript之declare

May 2, 2025

不妨从 @type/node 定义入手。

观察 @type/node 包的 package.json，可以发现其入口文件为 index.d.ts。

DefinitelyTyped/DefinitelyTyped/types/node/package.json

{
    "name": "@types/node",
    "types": "index"
}

入口文件的部分如下：

DefinitelyTyped/DefinitelyTyped/types/node/index.d.ts

/// <reference lib="es2020" />
/// <reference path="globals.d.ts" />
/// <reference path="fs.d.ts" />
/// <reference path="fs/promises.d.ts" />
/// <reference path="process.d.ts" />

显然，reference path 语法的作用是从指定文件模块中引入类型。
reference lib 则是引入内置库。

注：使用 /// <reference types="vite/client" /> 语法则可以从指定包中引入类型。

内置库的特点就是其定义的类型会变成 globalThis 全局模块中的类型，细节这里先按下不表。

lib.es2020.d.ts

/// <reference no-default-lib="true"/>

/// <reference lib="es2019" />
/// <reference lib="es2020.bigint" />
/// <reference lib="es2020.date" />
/// <reference lib="es2020.number" />
/// <reference lib="es2020.promise" />
/// <reference lib="es2020.sharedmemory" />
/// <reference lib="es2020.string" />
/// <reference lib="es2020.symbol.wellknown" />
/// <reference lib="es2020.intl" />

lib.es2020.full.d.ts

/// <reference no-default-lib="true"/>

/// <reference lib="es2020" />
/// <reference lib="dom" />
/// <reference lib="webworker.importscripts" />
/// <reference lib="scripthost" />
/// <reference lib="dom.iterable" />
/// <reference lib="dom.asynciterable" />

dom.d.ts

/// <reference no-default-lib="true"/>

interface Window {
    readonly window: Window & typeof globalThis;
}

declare var Window: {
    prototype: Window;
    new (): Window;
};

declare var window: Window & typeof globalThis;

type WindowProxy = Window;

@types/node 定义全局空间的方法如下：

DefinitelyTyped/DefinitelyTyped/types/node/global.d.ts

export {}; // Make this a module
declare global {
    var global: typeof globalThis;
    var process: NodeJS.Process;
    var console: Console;
}

@types/node 也定义了各个内置模块：

DefinitelyTyped/DefinitelyTyped/types/node/fs.d.ts

declare module "fs" {
    import { URL } from "node:url";
    export type PathLike = string | Buffer | URL;
    import * as promises from "node:fs/promises";
    export { promises };
}
declare module "node:fs" {
    export * from "fs";
}

DefinitelyTyped/DefinitelyTyped/types/node/fs/promises.d.ts

declare module "fs/promises" {}

DefinitelyTyped/DefinitelyTyped/types/node/process.d.ts

declare module "process" {
    global {
        var process: NodeJS.Process;
        namespace NodeJS {
            interface Process extends EventEmitter {}
        }
    }
    export = process;
    // 过时语法，等价于
    // export default process
}
declare module "node:process" {
    import process = require("process");
    export = process;
    // 过时语法，等价于
    // export * from "process"
}

declare module 语法仅能在 .d.ts 文件中使用，不能在 .ts 文件中使用：

example.d.ts

declare module "module-name" {
    global {
        interface PromiseConstructor {
            deferred<T>(): PromiseWithResolvers<T>;
        }
    }
}

下面的语法可以在 .d.ts 中使用，也可以在 .ts 文件中使用：

example.d.ts

declare global {
    interface PromiseConstructor {
        deferred<T>(): PromiseWithResolvers<T>;
    }
}
export {}; // This is required to make this file a module

注意到 typeof globalThis 等价于 module globalThis。
如果我们手动定义 globalThis 模块，实际上是定义 module "globalThis" 模块，
而非全局空间 module globalThis 模块（注意多余的引号）。

example.d.ts

declare module "globalThis" {}

example.ts

import globalThis2 from "globalThis";
type UserDefined = typeof globalThis2; // (alias) module "globalThis"
type BuiltIn = typeof globalThis; // module globalThis

直接通过 interface 关键字定义的接口不会与全局空间的同名接口合并（而是表现为覆盖同名全局标识符）。

type SimpleEqual<X, Y> = [X, Y] extends [Y, X] ? true : false;

// prettier-ignore
interface ObjectConstructor { 
    foo: "bar";               
} 

type Test = SimpleEqual<ObjectConstructor, { foo: "bar" }>; // false
type Test = SimpleEqual<ObjectConstructor, { foo: "bar" }>; // true

因此可以简单的认为，declare 关键字的作用就是用于向全局空间添加类型。

然而，declare 与 declare global 是不等价的！
简单来说：

declare 的语义是向当前模块空间内添加变量类型
declare global 的语义是向 module globalThis 模块中添加变量类型

我们看看下面的情况：

// 这里无论有没有 declare 效果相同
/** declare */ interface PromiseConstructor {
    deferred<T>(): PromiseWithResolvers<T>;
}
type PromiseDeferred = PromiseConstructor["deferred"]; // OK
const promiseDeferred = Promise.deferred; // Property 'deferred' does not exist on type 'PromiseConstructor'.
type PromiseAll = PromiseConstructor["all"]; // Property 'all' does not exist on type 'PromiseConstructor'.
const promiseAll = Promise.all; // OK

上述情况容易理解，因为 Promise 的类型为 globalThis.PromiseConstructor，而非我们定义的 interface PromiseConstructor。
因此，要修改 globalThis.PromiseConstructor，需使用 declare global 语法

declare global {
    interface PromiseConstructor {
        deferred<T>(): PromiseWithResolvers<T>;
    }
}
type PromiseDeferred = PromiseConstructor["deferred"]; // OK
const promiseDeferred = Promise.deferred; // OK

要说明 declare 与 declare global 的区别，给出如下示例：

注意 TypeScript 的这些概念与目标模块环境（compilerOptions.module）相关，本文模块环境统一为 ES 模块

declare const declareVar: "declareVar";
declare function declareFunction(): "declareFunction";
declare class DeclareClass {
    static declareClass: "declareClass";
}
declare global {
    const declareGlobalVar: "declareGlobalVar";
    function declareGlobalFunction(): "declareGlobalFunction";
    class DeclareGlobalClass {
        static declareGlobalClass: "declareGlobalClass";
    }
}

type A = Equal<typeof declareVar, "declareVar">;
type B = Equal<typeof declareFunction, () => "declareFunction">;
type C = Equal<typeof DeclareClass.declareClass, "declareClass">;

type D = Equal<typeof declareGlobalVar, "declareGlobalVar">;
type E = Equal<typeof declareGlobalFunction, () => "declareGlobalFunction">;
type F = Equal<typeof DeclareGlobalClass.declareGlobalClass, "declareGlobalClass">;

type _ = Equal<typeof globalThis.foobar, any>; // 类型为 any，不会报错
type G = Equal<typeof globalThis.declareVar, any>; // 类型为 any，而不是 "declareVar"
type H = Equal<typeof globalThis.declareFunction, any>; // 类型为 any，而不是 () => "declareFunction"
type I = Equal<typeof globalThis.DeclareClass.declareClass, any>; // 类型为 any，而不是 () => "declareFunction"
// @ts-expect-error: Property 'declareGlobalVar' does not exist on type 'typeof globalThis'.
type J = Equal<typeof globalThis.declareGlobalVar, "declareGlobalVar">; // 报错
type K = Equal<typeof globalThis.declareGlobalFunction, () => "declareGlobalFunction">;
//@ts-expect-error: Property 'DeclareGlobalClass' does not exist on type 'typeof globalThis'.
type L = Equal<typeof globalThis.DeclareGlobalClass.declareGlobalClass, "declareGlobalClass">; // 报错

type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;

观察上例，我们可以得到一个不符合直觉（但确实是事实）的结论：
globalThis 变量上访问任意属性，得到的类型为 any，但使用 declare global 定义类型后，该属性则无法找到（报错），然而 declare global function 是一个特例。

←Back to home

This work is licensed under CC BY-NC-SA 4.0