根本原因是tsserver按node_modules层级向上查找@types时加载了错误版本的声明文件，导致类型提示缺失、any泛滥、跳转失败；需通过typeRoots显式指定路径或dedupe扁平化依赖来解决。
为什么 node_modules 嵌套过深会让 TypeScript 推导“失灵”
根本原因不是 TS 本身出错，而是 tsserver 在解析类型时，会按 node_modules 层级向上查找 @types 和 types 字段，一旦遇到多个同名包（比如 lodash 或 react）分布在不同层级的 node_modules 中，TS 就可能加载错版本的声明文件，导致类型提示缺失、any 泛滥、跳转失败。
典型现象包括：import 后无自动补全、Ctrl+Click 跳不到定义、hover 显示 any、tsconfig.json 里写了 "types": ["node"] 却不生效。
检查当前 TS 类型解析路径用 tsserver 日志
VSCode 的 TS 插件底层是 tsserver，它默认静默运行。要确认它到底加载了哪个 node_modules 下的类型，必须打开日志：
Rydberg Agent Node
下载
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
- 在 VSCode 中按
Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入并执行Typescript: Toggle TS Server Log - 重启 TS 服务（命令面板执行
Typescript: Restart TS server） - 在任意
.ts文件中触发一次类型 hover 或跳转，然后打开输出面板 → 选择TypeScript标签 - 搜索关键词
resolved或node_modules，你会看到类似：Info 231 [10:22:45.123] Project: /path/to/project/tsconfig.json Detected file add: node_modules/lodash/index.d.ts
—— 注意路径是否来自最外层node_modules，还是某个子依赖下的node_modules/lodash
强制 TS 只读最外层 node_modules 的三种实操方式
目标是让 tsserver 忽略所有嵌套 node_modules 中的类型声明，只信任项目根目录下的 node_modules。这不是靠删包解决，而是控制解析策略：
-
方案一（推荐）：在
tsconfig.json中启用"typeRoots"并显式指定
添加："typeRoots": ["./node_modules/@types"]
。这会屏蔽所有node_modules/*/node_modules/@types路径，但要注意：如果项目用了yarn link或本地file:依赖，其类型需手动 symlink 到根@types目录下 -
方案二：用
npm dedupe或yarn dedupeyarn dedupe（需yarn@berry或yarn@3+）能扁平化重复依赖；npm dedupe效果有限，尤其在npm@8+中已弱化支持，不建议主用 -
方案三：禁用嵌套类型自动发现（VSCode 级）
在工作区.vscode/settings.json中加："typescript.preferences.includePackageJsonAutoImports": "auto",<br>"typescript.preferences.useLabelDetailsForAutoImports": true,<br>"typescript.preferences.includePackageJsonAutoImports": "off"
，再配合"typeRoots"使用，可进一步减少干扰
pnpm 用户注意：symlink 模式天然规避此问题，但仍有例外
pnpm 默认用硬链接 + 符号链接组织 node_modules，绝大多数情况下不会产生多层 @types 冲突。但以下情况仍会触发推导失效：
- 项目中存在
overrides或resolutions强制降级某包（如"react": "17.0.2"），而该版本对应的@types/react未同步安装到根@types - 使用了
pnpm recursive多包仓库，但子包各自有devDependencies里的@types/*，且未设"typeRoots"统一指向 workspace 根 -
pnpm的node_modules/.pnpm下的 symlink 被某些旧版 TS 插件误识别为“独立模块”，此时需升级 VSCode TS 插件至 v5.5+，并确认"typescript.preferences.useWorkspaceTsserver": true
真正麻烦的从来不是嵌套本身，而是不同类型版本混杂后，TS 选错了 index.d.ts 的那一刻——它不会报错，只会沉默地给你 any。所以别等出问题才查，每次新增依赖后，用 tsserver 日志快速扫一眼类型来源路径，比事后 debug 十分钟更省力。
