TypeScript API 报 TS2688：外部项目丢失 configFilePath

用 Node 脚本调用 TypeScript Compiler API 检查另一个目录中的项目，明明安装了 @types/react，却报 TS2688: Cannot find type definition file for 'react'。直接在目标项目目录检查正常，从工具目录调用就失败时，先看传给 Program 的编译选项是否保留了配置文件的位置。

这条路径适用于 TypeScript 5.3 至 6.0 的 JavaScript Compiler API。TypeScript 7 系列的接口需要按对应版本重新核对，不能直接沿用下面的 API 示例。它也不覆盖类型包确实没安装、名称拼错或包内容损坏的情况。

读取了 tsconfig，不等于 Program 知道它在哪里

常见代码先用 readConfigFile 读取目标 tsconfig.json，再调用 parseJsonConfigFileContent，并把 fileNames、options 传入 createProgram。给解析函数传了 basePath，可以让部分文件路径正确展开，但如果没有把配置文件的位置继续带进 options，Program 仍可能缺少 configFilePath。

默认类型根目录的计算会先看显式 typeRoots，再看 configFilePath 所在目录；没有这些信息时，会使用宿主的当前目录。工具进程的工作目录与目标项目不同，查找起点也就可能不同。目标项目下存在 node_modules/@types/react，并不能保证这次调用搜索了那里。

先对照实际 tsconfig 绝对路径、目标项目的依赖目录和传入 Program 的 options.configFilePath。错误后面若写着 Entry point of type library 'react' specified in compilerOptions，表示它正在处理 types 配置中的类型库入口，不能仅把它当成业务代码某条 import 失败。

如果 configFilePath 已正确保留，再检查该类型包是否安装在目标环境、types 的名称、显式 typeRoots 和其他解析配置。安装在工具自身目录里的依赖，与目标项目依赖未必是同一套。

从配置文件入口解析，保留位置和诊断

对普通磁盘项目，可以用 getParsedCommandLineOfConfigFile 解析指定配置。下面是 CommonJS 工具脚本的局部示例，target-ts-project 是示例目录；TypeScript 由工具项目自身已安装的依赖提供：

const ts = require('typescript');
const path = require('node:path');

const configPath = path.resolve('target-ts-project', 'tsconfig.json');
const formatHost = {
  getCanonicalFileName: file => file,
  getCurrentDirectory: ts.sys.getCurrentDirectory,
  getNewLine: () => ts.sys.newLine
};
const report = diagnostic => {
  console.error(ts.formatDiagnosticsWithColorAndContext([diagnostic], formatHost));
};
const parsed = ts.getParsedCommandLineOfConfigFile(
  configPath,
  { noEmit: true },
  { ...ts.sys, onUnRecoverableConfigFileDiagnostic: report }
);
if (!parsed) throw new Error('Cannot parse project configuration');
if (parsed.errors.length) {
  parsed.errors.forEach(report);
  throw new Error('Project configuration contains errors');
}
const program = ts.createProgram({
  rootNames: parsed.fileNames,
  options: parsed.options,
  projectReferences: parsed.projectReferences
});
ts.getPreEmitDiagnostics(program).forEach(report);

该函数会以配置文件的位置建立解析上下文，并把绝对配置路径传下去。读取失败可能返回 undefined；配置诊断也需要先处理，不能继续用一份不完整配置解释后面的类型错误。示例只收集诊断，不调用 emit；若作为 CI 门禁，还应按工具现有规则将错误诊断转换为失败状态。

这里 path.resolve 仍以工具进程的当前目录解释示例路径。外部任务传入项目地址时，应先把那个地址解析为明确的绝对路径，再定位 tsconfig，不能让每个调用者各自猜目录。项目引用也不意味着这段单个 Program 示例完成了所有引用项目的构建；需要构建依赖时，应使用项目既有的构建流程。

不用收窄 typeRoots 掩盖丢失的上下文

显式指定目标项目的 typeRoots 可能让眼前的类型包被找到，但会改变允许搜索的类型根目录。原本依赖父目录、工作区提升依赖或其他类型目录的项目，可能因此丢失另外一些声明。

如果项目本来就需要限定 typeRoots，可以保留它，并核对解析后的绝对路径和所需类型包。若只是为了绕过工具 API 忘记配置位置，优先修正解析入口。types 也控制要进入全局范围的类型库，不应为了消除一个错误就随意删除，改变项目原有类型环境。

不建议用全局 process.chdir 修一个检查请求。长期运行的工具可能同时处理多个项目，改变整个进程的目录会影响其他文件访问。通过配置路径与宿主上下文表达目标项目，更容易保持不同任务的边界。

验收仍使用原来的工具入口

保存工具代码和相关配置后，在获准的项目环境由原入口重新检查。确认传入 Program 的 configFilePath 指向目标 tsconfig，预期源码仍进入检查，目标类型库能从该项目的环境解析，不再出现原来的 TS2688。

随后检查其他类型声明和项目诊断，避免只找到 React，却丢了原来需要的 Node 或测试框架类型。错误仍在时，可以在诊断环境启用 traceResolution 查看实际查找目录；日志可能包含项目路径，分享前按项目规则处理。

回退时恢复工具代码与配置，不需要删除目标项目的整个依赖目录。若同时更新 TypeScript 版本，也要恢复对应锁文件和工具依赖，避免把 API 变更与路径修复混在同一轮判断里。