TypeScript 服务在 VSCode 右下角持续加载

Question

TypeScript 服务在 VSCode 右下角持续显示“正在加载…”是常见问题，通常由大型项目、语法错误或配置不当引发。可能原因包括：tsconfig.json 配置错误、node_modules 冗余、工作区包含过多非项目文件，或 VSCode TypeScript 版本与项目不匹配。此外，插件冲突或语言服务器启动失败也会导致此问题。可通过切换使用工作区版本的 TypeScript、清理缓存、排除无关文件或禁用不必要的扩展来排查解决。

Answer 1

一、现象描述与初步定位

在使用 Visual Studio Code 开发 TypeScript 项目时，右下角持续显示“正在加载…”是开发者常遇到的问题。该状态意味着 TypeScript 语言服务器（TypeScript Server, TSServer）未能完成初始化或陷入阻塞。

此问题在大型单体项目、Monorepo 架构或多工作区环境中尤为常见。初步判断可通过以下方式：

• 检查 VSCode 右下角 TypeScript 版本提示
• 打开命令面板执行 “TypeScript: Open TS Server Log” 查看日志
• 观察 CPU 占用是否异常升高

二、常见原因分类分析

类别	具体原因	典型表现
配置问题	tsconfig.json 路径错误或包含过多文件	TSServer 扫描大量非必要文件
依赖问题	node_modules 过大或存在损坏包	初始化耗时过长或内存溢出
版本不匹配	VSCode 使用内置 TS 而项目依赖较新版本	类型检查失败或功能缺失
插件冲突	ESLint、Prettier 或其他语言类扩展干扰	服务启动失败或响应延迟
项目结构	工作区包含大量非源码目录（如 dist、build）	文件监听列表膨胀

三、深入排查路径与诊断流程

为系统化解决该问题，建议遵循以下诊断流程图进行逐层排除：

```mermaid
graph TD
    A[TS Server 显示“正在加载…”] --> B{是否为大型项目?}
    B -->|是| C[检查 tsconfig.json include/exclude 配置]
    B -->|否| D[检查 node_modules 是否冗余]
    C --> E[优化文件包含范围]
    D --> F[删除 node_modules 并重装]
    E --> G[重启 TS Server]
    F --> G
    G --> H{是否恢复正常?}
    H -->|否| I[切换至工作区 TypeScript 版本]
    I --> J[禁用非必要扩展测试]
    J --> K{是否恢复?}
    K -->|是| L[定位冲突插件]
    K -->|否| M[清除 VSCode TS 缓存]
    M --> N[验证 TSServer 日志]
```
    

四、核心解决方案详解

1. 切换 TypeScript 版本：在 VSCode 底部栏点击 TypeScript 版本号，选择“Use Workspace Version”，确保与项目 devDependencies 中的 typescript 一致。
2. 优化 tsconfig.json：明确 include 和 exclude 字段，避免扫描 node_modules、dist 等目录。

   {
     "include": ["src"],
     "exclude": ["node_modules", "dist", "build", "**/*.test.ts"]
   }
   

3. 清理缓存：关闭 VSCode，删除以下路径：
   • macOS: ~/Library/Application Support/Code/User/workspaceStorage
   • Windows: %APPDATA%\Code\User\workspaceStorage
   • Linux: ~/.config/Code/User/workspaceStorage
   并清除 ~/.cache/typescript。
4. 限制工作区范围：使用 .vscode/settings.json 设置文件排除规则：

   {
     "typescript.tsserver.trace": "verbose",
     "typescript.tsserver.pluginPaths": [],
     "files.watcherExclude": {
       "**/node_modules/**": true,
       "**/dist/**": true
     }
   }
   

5. 插件隔离测试：以“干净模式”启动 VSCode（code --disable-extensions），逐步启用扩展以识别冲突源。

五、高级调试手段与长期维护建议

对于复杂 Monorepo 或跨团队协作项目，建议建立标准化的开发环境规范：

• 统一 TypeScript 版本并通过 npm overrides 或 yarn resolutions 锁定
• 使用 inferredProjectCompileOptions 控制未配置项目的编译行为
• 启用 typescript.preferences.includePackageJsonAutoImports 减少自动导入开销
• 定期运行 tsc --noEmit --diagnostics 监控编译性能
• 结合 TypeScript Plugin for VSCode 提供的性能面板进行调优