ast节点解析失败时textdocument/documentsymbol返回空数组，根本原因是语言服务器未加载成功，如ts项目缺失tsconfig.json或python中pylance未激活；需检查右下角语言模式、输出面板报错、node_modules/typescript版本≥4.5，并重启语言服务器。
AST节点解析失败时，textDocument/documentSymbol 返回空数组怎么办
常见现象是调用 LSP 的 documentSymbol 方法后没返回任何符号，或只返回顶层节点。根本原因不是插件写错了，而是语言服务器压根没加载成功——比如 TypeScript 项目里没识别出 tsconfig.json，或 Python 项目中 Pylance 未激活。
排查优先级如下：
- 检查右下角语言模式是否正确（如显示“TypeScript”而非“Plain Text”）
- 打开输出面板（
Ctrl+Shift+U），切换到Typescript或Python标签页，确认无Failed to load configuration类报错 - 对 TS/JS 项目，确保
node_modules/typescript存在且版本 ≥ 4.5；旧版不支持完整的 AST 节点映射 - 重启语言服务器：命令面板执行
Developer: Restart Language Server
如何验证 AST 是否真能定位到某行某列的语法节点
VSCode 不提供直接“点击代码→打印 AST 节点”的 UI 功能，但可通过调试协议手动触发。关键路径是：先用 textDocument/semanticTokens/full 获取语义 token 列表，再结合光标位置反查所属 AST 节点类型。
更实用的做法是启用 VSCode 内置的 AST 可视化调试入口：
- 在任意 TS/JS 文件中按
Ctrl+Shift+P，运行Developer: Toggle Developer Tools - 在控制台输入
vscode.workspace.textDocuments[0].languageId确认文档已注册语言服务 - 执行
vscode.languages.getLanguages()查看当前激活的语言 ID 列表 - 若需深度验证，可临时加断点到插件的
onDidChangeTextDocument回调中，打印event.document.getText()和event.contentChanges，比对 AST 解析前后是否一致
自定义插件里解析 AST 后，为什么 Range 定位总偏移 1 行或 1 列
这是字符编码与换行符处理不一致导致的典型问题。VSCode 内部统一使用 \n 作为行分隔符，而本地文件若含 \r\n（Windows）或 \r（旧 Mac），会导致行号计算偏差。
解决方式必须在解析前 Normalize 文本：
- 读取文档内容后，先执行
text.replace(/\r\n/g, '\n').replace(/\r/g, '\n') - 不要依赖
document.lineAt(pos.line).text直接切片，应使用document.offsetAt(pos)转为绝对偏移再匹配 AST 节点 - 若用
typescript包解析，务必传入createSourceFile(..., { setParentNodes: true })，否则父节点引用为空，影响作用域判断 - 注意：TS 的
Node.getStart()默认返回包含前导空白的起始位置，若需精确到 token 起点，改用Node.getFullStart()
Vue/React 模板中 JSX/Template AST 为何无法被普通语言服务器识别
因为标准 TypeScript 或 JavaScript 语言服务器只解析 .ts/.js 文件中的 JS 表达式，不处理 .vue 单文件组件里的 <template></template> 或 React 中的 JSX 标签树。它们属于不同语法域，需框架专属解析器。
可行方案只有两类：
- 用
volar（Vue）或typesciprt-plugin-jsx（React）这类框架感知型语言服务器，它们会在 parser 阶段将模板编译为 TS AST 节点并注入额外属性（如__vueParentComponent） - 不走 LSP，改用构建阶段 AST 分析：比如
code-inspector-plugin在 Vite 插件中通过transformhook 拦截 SFC 内容，用@vue/compiler-sfc提取 template AST，再绑定行号信息 - 切记：动态生成的 DOM（如
innerHTML = '<div>xxx</div>'）永远无法被静态 AST 工具定位，这是技术边界，不是配置问题
AST 节点定位真正卡住的地方，往往不在解析逻辑本身，而在文本归一化、语言服务激活状态、以及模板与脚本的语法域隔离这三处。跨框架时尤其要注意解析器是否真的“看见”了你认为它该看见的内容。
