文件大纲不显示主因是语言服务器未正常启动，需检查其运行状态、文件语言模式是否正确、插件配置是否启用符号索引，以及工作区设置是否覆盖了相关功能。

为什么文件大纲（Outline）不显示？先看语言服务器是否启动

文件大纲依赖对应语言的 Language Server 正常运行，不是插件装了就自动生效。如果 Outline 视图空白、右键“Go to Symbol in Workspace”无响应，大概率是语言服务根本没起来。

检查方法很简单：打开命令面板（Ctrl+Shift+P），输入并运行 Developer: Toggle Developer Tools，切换到 Console 标签页，搜索关键词 "language server" 或 "failed to start"。常见错误包括：

• Error: Cannot find module 'vscode-languageclient' → 插件依赖未安装，多见于手动拷贝插件或离线安装失败
• spawn node ENOENT → 插件配置里指定了不存在的 node 路径，或系统没装 Node.js
• Connection to server got closed → 语言服务器进程崩溃，常因内存不足或配置错（如 "python.defaultInterpreterPath" 指向一个无法执行的 Python）

检查当前文件是否被语言服务识别

VSCode 的大纲只对“被激活语言模式”的文件生效。即使你打开了 .py 文件，如果右下角状态栏显示的是 Plain Text 而非 Python，那语言服务压根不会加载，Outline 自然为空。

解决步骤：

• 点击右下角语言标识（如 Plain Text），选择正确语言（如 Python）
• 确认文件后缀是否在插件支持列表中（例如某些 Rust 插件不处理 .rs.in）
• 检查 .vscode/settings.json 是否有误配的 "files.associations"，把本该归 Python 管的 .ipynb 强行映射成 jsonc
• 对 TypeScript/JavaScript，确保项目根目录存在 tsconfig.json 或 jsconfig.json，否则语言服务可能降级为“基础模式”，不提供符号索引

插件自身配置导致 Outline 被禁用

不少语言插件默认关闭大纲符号解析以节省资源，尤其在大仓库中。这不是 Bug，是主动策略。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

典型可调配置项（在 settings.json 中检查）：

• "python.analysis.extraPaths" 缺失 → 导致 import 模块无法解析，符号树截断
• "typescript.preferences.includePackageJsonAutoImports" 设为 "auto" 但项目没 package.json → 符号发现逻辑卡住
• "editor.showUnused" 开启时，某些插件会跳过未引用符号的索引 → 大纲看起来“缺失”部分函数
• "html.suggest.html5" 关闭 → HTML 文件的大纲只剩 级别，不展开内部标签

工作区设置覆盖了用户级语言配置

这是最容易被忽略的一层干扰：你在用户设置里开了 Python 语言服务，但当前工作区的 .vscode/settings.json 里写了 "python.enabled": false 或 "editor.codeActionsOnSave" 里禁用了 "source.organizeImports"，这些都可能连带抑制符号收集流程。

排查建议：

• 临时重命名当前工作区的 .vscode 文件夹，重启 VSCode，看 Outline 是否恢复
• 对比用户设置（Ctrl+, → 左下角点击“Open Settings (JSON)”）和工作区设置里的语言相关字段
• 特别注意 "*": { ... } 这类通配符配置，它会全局覆盖，包括大纲行为
• 如果使用 Remote-SSH 或 WSL，确认远程环境已安装对应语言运行时（比如远程没装 pyright，本地设置再全也没用）

Outline 加载不出，很少是插件本身坏了，更多是语言服务没拿到有效上下文——它需要正确的文件类型、可用的运行时、没被覆盖的配置，以及足够干净的进程环境。每一步都可能断链，而日志里那句 "No symbols found in document" 往往只是最后一环失效的提示，不是根因。