2.3 导航与重构：给墙上装挂板

2.3 导航与重构：给墙上装挂板

本节摘要：导航装备解决"东西在哪"，重构装备解决"整体改名不改坏"。本节先用内置的文件跳转、符号大纲与大文件 minimap 打底，再钉上书签、待办树、注释分组三件挂板，最后用语言服务的重命名能力完成跨文件安全改名。老项目与新项目都吃得开。

「技术债」这个词你多半听过，但债真正的利息藏在哪？藏在"找东西"上。一个几千文件的老仓库，改一个函数签名，牵连面横跨几十个文件；定位一处逻辑，要在面包屑与滚动条之间来回横跳。工匠的车间墙上有一整面挂板，每件工具都有固定的钩位——抬手就到，用完归位。编辑器的导航装备就是这面挂板，重构装备则是把整排工具连底座挪走还不散架的吊装设备。这一节承接前两节的输入输出装备，补上"移动"这道工序。

适用场景：你的墙上缺不缺挂板

三类信号说明该装了。信号一，经常在最近打开的文件之间来回横跳，靠的是记忆而不是路径——缺固定钩位。信号二，代码里散落着"待办""临时方案"标记，事后想统一清点却找不到——缺集中看板。信号三，全局搜索某个标识符然后逐处手改——这不是重构，这是走钢丝，缺安全吊装。

先用足内置挂板

上插件之前，内置的导航能力要用到位。文件名跳转：命令面板里输入文件名，模糊匹配直达，是频次最高的移动方式；符号跳转：在当前文件里直接列函数与类的大纲，长文件里下钻一层就能定位；工程级符号搜索则跨文件找定义。资源管理器的大纲视图把当前文件的符号结构画成树，配合"转到定义""查找所有引用"这对组合拳，多数导航任务不开插件就能闭环。这些能力的后台就是第 1 章讲的语言服务——语言服务越懂你的项目，导航越准。

内置打底配置如下，把大纲与面包屑都立起来：

{
  "breadcrumbs.enabled": true,
  "editor.minimap.enabled": true,
  "editor.stickyScroll.enabled": true
}
​

粘性滚动值得单独一提：长文件里滚到中段，当前所处的作用域顶部会钉在编辑器顶沿，相当于卷尺上永远露着当前刻度，写深层嵌套代码时极省心。

钉三块挂板：书签、待办树、注释分组

第一块，书签。 把常用的几处代码位置钉上标记，快捷键在标记间循环跳转。典型用法：调试时把可疑点全部钉上，一轮复现下来挨个跳着看；重构时把待改的旧接口调用点钉上，改一处跳下一处，不怕漏。

第二块，待办树。 代码注释里的待办标记会被收进一棵侧栏树，按文件分组，点一项跳一处。它的价值在于把散落的"回头再改"变成可清点的工单池——每周扫一眼树，过期项当场处理或转成议题。常用标记约定可以扩展到自己的工作流：

{
  "todo-tree.general.tags": [
    "TODO",
    "FIXME",
    "HACK",
    "REVIEW",
    "DEPRECATED"
  ],
  "todo-tree.highlights.enabled": true
}
​

第三块，注释分组。 让不同前缀的注释显示成不同颜色：警示类标红、问题类标黄、说明类标绿，扫一眼代码就能看出哪段是正常逻辑、哪段是带伤运行。三块挂板都很轻，性能档位与主题相当，装了不心疼。

重构：安全吊装怎么做

导航管"找到"，重构管"改对"。重中之重是跨文件重命名：光标落在标识符上，触发重命名命令，语言服务解析整个项目的引用关系，预览所有将受影响的位置，确认后一次改齐。这与全局搜索替换有本质区别——前者理解语法结构，只会动真正的引用；后者只认字符串，注释里、文档里、无关字符串里的同名文本全遭殃。同理还有"安全删除"（有引用就不让删）、"提取变量/函数"（把内联逻辑抽成具名单元）这两个常用动作，都走语言服务的同一套安全机制。

一个对照实验最能说明差距：在某前端项目里把一个导出组件改名，字符串替换路线事后补修了三处误伤（注释、测试快照、同名的样式类）；重命名路线一次通过，因为语言服务顺带改写了所有导入语句。能走重命名就别走搜索替换，这是老工位传下来的铁律。

坑点提醒

坑一，重命名不彻底。 语言服务只能改它"看得懂"的引用；字符串拼接出来的调用、动态派发的属性、跨仓库的引用都看不见。重命名后仍要跑测试与全局搜索兜底。坑二，书签失效。 书签锚定行号，代码一改行就漂移；重要位置改用符号级书签或待办标记，跟着符号走。坑三，待办树变垃圾场。 只进不出的待办标记会让人渐渐无视整棵树——给它定个清点节奏，与版本控制的提交节奏对齐。

替代方案

导航的极简替代是纯键盘流：文件跳转、符号跳转、转到定义三个快捷键练到肌肉记忆，不装任何挂板，适合小仓库。重构的替代是走命令行的专用重构工具（各语言生态都有自己的重构引擎），批量重构大仓库时更稳，日常单点改名则不如编辑器内顺手。书签的替代是"多窗口分屏"：把要对照的几处并排摆开，不用跳——但窗口数量有限，超过对照上限还是得靠钩位。

常见疑问快答

问：书签、待办标记、大纲，三者会不会功能重叠？答：三者的锚定对象不同——书签锚“位置”，待办锚“债务”，大纲锚“结构”。一间工位里三者各司其职：调试时钉书签，还债时扫待办树，迷路时看大纲。重叠的不是功能，是“都想帮你找东西”的好意。

问：为什么全局搜索替换不被推荐做改名？答：搜索替换只认字符串，不理解语法——注释里的提及、文档里的引用、同名的无关标识符全会被误伤；而语言服务的重命名理解引用关系，只动真引用。改名走重命名、查文本走搜索，两把工具各守本分。

问：大仓库里“转到定义”偶尔失灵，怎么办？答：先确认该文件的语言服务是否就绪（索引未完成时跳转能力是残缺的）；再看目标是否跨了语言边界或经动态派发——这两类引用天然不可见。失灵时的兜底是符号搜索加人工确认，事后补一个书签，别依赖下次还能搜到。

问：重构前要不要先跑一遍测试？答：要，而且这是重构的准入条件——有绿测试兜底的重构才叫重构，没有测试的重构叫赌运气。测试不全的老代码，先补关键路径的测试再动手，这个顺序在哪个语言里都成立。

收束与下一站

挂板钉好，吊装就位，"找东西"和"改名字"这两类高频动作都有了安全通道。下一节处理工序里最揪心的一段——出问题了怎么办：调试辅助装备登场，行内错误显示与断点档位，把工位的万用表配齐。