如何通过TypeScript编译器API判断符号是否为全局符号？

嘿，我刚好在开发TypeScript语言服务插件时碰到过几乎一模一样的需求，来给你梳理下怎么解决这个问题。

你的核心需求是区分三种符号：本地声明的变量、全局作用域符号、外部模块导入的符号，只禁止最后一种。我们可以结合ts.SymbolFlags和getDeclarations()来实现这个判断，两者配合比单独用某一种更可靠。

核心思路 #

1. 本地符号：声明直接存在于当前处理的源文件中；
2. 全局符号：带有Global标志，且声明来自全局作用域（比如内置的lib.d.ts，或者用户写的无模块脚本）；
3. 外部模块符号：既不是本地也不是全局的，通常是通过import引入的，声明在外部文件中。

具体判断逻辑 #

1. 先获取符号 #

首先你已经知道用typeChecker.getSymbolAtLocation(identNode)获取符号，第一步要先判断符号是否存在：

const symbol = typeChecker.getSymbolAtLocation(identNode);
if (!symbol) {
  // 处理无符号的情况，比如语法上的标识符但未绑定任何声明
  return false;
}

2. 判断是否为本地符号 #

通过getDeclarations()获取符号的所有声明，检查是否有声明位于当前源文件内：

const currentSourceFile = identNode.getSourceFile();
const hasLocalDeclaration = symbol.getDeclarations()?.some(decl => decl.getSourceFile() === currentSourceFile);
if (hasLocalDeclaration) {
  // 本地声明的符号，允许引用
  return true;
}

3. 判断是否为全局符号 #

检查符号的flags是否包含SymbolFlags.Global，同时可以进一步验证声明是否来自全局作用域（避免误判某些特殊情况）：

if (symbol.flags & ts.SymbolFlags.Global) {
  // 可选：验证声明是否来自全局库文件或无模块脚本
  const isGlobalScopeDecl = symbol.getDeclarations()?.some(decl => {
    const sf = decl.getSourceFile();
    // 全局库文件（比如lib.d.ts）或者无模块脚本（没有import/export的文件）
    return sf.isDeclarationFile || !sf.moduleName;
  });
  if (isGlobalScopeDecl) {
    // 全局符号，允许引用
    return true;
  }
}

4. 剩下的就是外部模块符号 #

如果上面两个条件都不满足，那这个符号肯定是来自外部模块的，需要触发警告。

关于Transient标志的解释 #

你提到的SymbolFlags.Transient是TypeScript内部使用的标志，代表这个符号是临时生成的，不是用户显式声明的。比如：

• 类型推断过程中创建的临时符号（比如对象字面量的属性符号）；
• 泛型类型参数的实例符号；
• 某些合成的中间符号。

这类符号通常不需要处理，因为你的需求只关心用户自己声明或导入的内容，碰到带有Transient标志的符号可以直接跳过判断。

完整代码示例 #

把上面的逻辑整合起来，就是一个可以直接用的判断函数：

function isSymbolAllowed(
  identNode: ts.Identifier,
  typeChecker: ts.TypeChecker
): boolean {
  const symbol = typeChecker.getSymbolAtLocation(identNode);
  if (!symbol) return false;

  // 跳过临时符号
  if (symbol.flags & ts.SymbolFlags.Transient) return true;

  const currentSourceFile = identNode.getSourceFile();

  // 检查是否是本地声明
  const hasLocalDecl = symbol.getDeclarations()?.some(decl => decl.getSourceFile() === currentSourceFile);
  if (hasLocalDecl) return true;

  // 检查是否是全局符号
  if (symbol.flags & ts.SymbolFlags.Global) {
    const isGlobalDecl = symbol.getDeclarations()?.some(decl => {
      const sf = decl.getSourceFile();
      return sf.isDeclarationFile || !sf.moduleName;
    });
    if (isGlobalDecl) return true;
  }

  // 外部模块符号，禁止引用
  return false;
}

注意事项 #

• 对于通过import type导入的类型符号，如果你不需要检查类型引用，可以额外判断symbol.flags & ts.SymbolFlags.Type来跳过；
• 有些全局符号可能来自用户自定义的全局声明文件（比如global.d.ts），上面的逻辑也能覆盖到，因为这类文件是isDeclarationFile；
• 如果你的插件需要处理declare global块内的声明，这类声明也会带有Global标志，同样会被判定为允许的全局符号。

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