TypeScript TS2304 — 找不到名称

症状

本篇调试指南针对“TypeScript TS2304 — 找不到名称”。内容涵盖可观察的症状、可复现的诊断路径、根本原因、具体修复方式，以及如何验证修复并防止回归。

可观察到的症状包括：

• error TS2304: Cannot find name ‘process’（或 Buffer、describe）
• 编辑器标红，但构建有时通过
• 运行期可用但 TypeScript 不认识

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

npx tsc --noEmit 2>&1 | grep TS2304

缺失的名称决定应导入它，还是添加其环境类型。

步骤 2

grep -n '"types"\|"lib"' tsconfig.json

缺少 “types”: [“node”, “jest”] 条目即解释了 Node/测试全局为何不被识别。

常见诱因（按出现频率排序）：

• 符号未导入到该文件
• 全局类型（Node 或测试全局）未加入 types 选项
• 标识符拼写或大小写错误

根因

TypeScript 从本地声明、导入与配置的环境类型包中解析名称。仅存在于运行期或未配置包中的名称对类型检查器不可见，因而报 TS2304。

修复

为本地符号添加导入，安装相关 @types 包并在 compilerOptions.types 中列出，或为确实全局的运行期值为其编写 d.ts 声明。

注意：声明不存在的全局会在无实际值的情况下压制错误；只声明真实的全局。

// local symbol must be imported
import { describe, it, expect } from 'vitest';
import { Buffer } from 'node:buffer';

// tsconfig.json
{
  "compilerOptions": {
    "types": ["node", "vitest/globals"]
  }
}

// ambient global for a runtime-provided value
// globals.d.ts
declare const __APP_VERSION__: string;

验证

运行 tsc –noEmit 并确认 TS2304 消失；用冒烟测试确保运行期仍有该符号。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。