如何声明TypeScript函数签名，限制仅全局或无上下文执行？

你遇到的这个问题，本质是TypeScript默认的类型推断没有体现JavaScript运行时的this绑定限制。先理清楚前后背景，再给出针对性的解决方案：

JavaScript运行时的行为回顾 #

在浏览器环境中，setTimeout这类全局API要求调用时的this必须是window（或者null/undefined，此时会自动绑定到window）。如果把它挂载到普通对象上调用，就会抛出Uncaught TypeError: Illegal invocation：

var x = { setTimeout: setTimeout };
x.setTimeout(() => console.log(1)); // 报错
(0, x.setTimeout)(() => console.log(2)); // 正常执行，因为逗号运算符让函数以全局上下文调用

TypeScript当前的问题 #

但TypeScript默认的类型系统没有捕捉到这个限制：

function f() { }
var x = { setTimeout };
x.setTimeout(f); // JS运行时会报错，但TS无任何提示
(0, x.setTimeout)(f); // TS错误提示"逗号运算符左侧未使用且无副作用"，但实际这是改变`this`的关键操作

你尝试过显式声明this类型，但没法同时实现：让带对象上下文的调用报错，让无上下文的调用通过（或仅提示无副作用）。

解决方案：显式约束函数的this类型 #

我们可以利用TypeScript的显式this参数特性，明确指定函数只能在this为void（无绑定上下文）或全局Window对象的情况下被调用。

1. 重新声明全局setTimeout的类型 #

先给setTimeout加上this约束：

// 定义一个通用类型：只能在全局/无上下文执行的函数
type GlobalOnlyFunction<T extends (...args: any[]) => any> = 
  (this: void | Window, ...args: Parameters<T>) => ReturnType<T>;

// 覆盖全局setTimeout的类型
declare function setTimeout: GlobalOnlyFunction<typeof setTimeout>;

2. 测试效果 #

现在再写之前的代码，就能得到预期的类型检查结果：

function f() { }
var x = { setTimeout };

// ✅ 此处TS会报错：类型“{ setTimeout: GlobalOnlyFunction<typeof setTimeout>; }”的“this”上下文不能分配给方法的“this”类型“void | Window”。
x.setTimeout(f); 

// 逗号运算符的提示问题：TS认为0是无副作用表达式，用类型断言绕过
(0 as any, x.setTimeout)(f); // ✅ 无类型错误，JS执行正常
// 或者用更语义化的解构方式（效果和逗号运算符一致）
const { setTimeout: globalSafeSetTimeout } = x;
globalSafeSetTimeout(f); // ✅ 完全正常，无任何提示

3. 原理说明 #

• 当我们给函数指定this: void | Window时，TypeScript会严格检查调用时的上下文：
  • 通过对象属性调用（x.setTimeout）时，this指向x，不符合约束，所以报错，完美匹配JS运行时的错误场景。
  • 直接调用（解构后、逗号运算符调用）时，this是void（严格模式）或window（非严格模式），符合约束，所以通过检查。
• 逗号运算符的提示是TS的静态分析结果，它不知道0在这里是为了改变this绑定，用0 as any可以绕过这个提示，而解构的方式更清晰，也不会有TS提示。

自定义类似函数的处理方式 #

如果是你自己写的需要全局上下文的函数，可以直接在定义时指定this类型：

function myGlobalApi(this: void | Window, callback: () => void) {
  // 运行时也可以加上检查，和TS类型约束对应
  if (this !== window && this !== undefined) {
    throw new Error("Illegal invocation");
  }
  console.log("执行全局API");
  setTimeout(callback);
}

const obj = { myGlobalApi };
obj.myGlobalApi(() => {}); // ✅ TS报错：this上下文不匹配
myGlobalApi(() => {}); // ✅ 正常
(0 as any, obj.myGlobalApi)(() => {}); // ✅ 正常

这样就能完全实现你的需求：让函数只能在全局或无上下文环境下执行，同时TypeScript能准确区分合法和非法的调用方式。

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