Lesson 02 · 定位术

同事发来一张截图，怎么找到该改的那一行

从界面文字走到组件、API 与副作用。起手分三条岔路，走完通常不到 15 分钟。

先热身：把课 01 取出来

不要往回翻。这两题是检索练习，取不出来也先点一个——回忆失败本身也在加固记忆。

先说人话：这一课解决的是什么场面

美术在群里发一张截图：「游戏资源库里我点了资源卡片上的替换，弹了『更新成功』，但资源没变。」 配一张框住那个按钮的图。没有报错信息，没有堆栈，没有接口名。

你现在要做的第一件事不是修它，而是回答一个更基础的问题： 这句「替换」对应的代码在哪个文件的第几行？

接手一个陌生项目，绝大多数时间不是花在「怎么改」上，是花在「改哪里」上。 课 01 给了你一条纵向链路（一个值怎么从 .env 走到请求头）； 这一课给你一条横向链路：从用户能看见的东西，走到你能编辑的那一行。

定位四步：起手分三条岔路

终点总是一样的（组件 → import 块 → API 层），但起手有三条岔路， 取决于你手上那句界面文字是什么性质。 不要硬走路由表——本课自己的案例就跳过了它。

为什么强调这个：路由表是最容易先入为主的一步，但 GameBox 有相当多界面根本不经过路由。 走 A 的多是菜单和页面标题，走 B 的是绝大多数按钮，走 C 的是 GM 弹窗那一类——它在 src/App.vue:12 被直接 import、在 src/App.vue:148 渲染，地址栏自始至终不变。

第 1 步：先分清这句文字是 A 还是 B

GameBox 的中文文案没有统一走 i18n。两种情况：

「游戏资源库」这几个字在 src/locales/zh-CN.ts:117，是 router 段的一条 （整段是 src/locales/zh-CN.ts:113-141）。 而资源卡片上那个「替换」按钮是硬编码，在 src/views/Workspace/Components/ViewCard.vue:184。 它不是右键菜单——鼠标停在卡片上时，右上角会出现一排按钮 （src/views/Workspace/Components/ViewCard.vue:104-110）， 「替换」是其中一个。

实践建议：先 rg "那句中文" src，一步命中就赚了。 命中不了再去 src/locales/zh-CN.ts 找 key。反过来做会慢一倍， 因为走 i18n 的文案在这个项目里是少数。

src/locales/zh-CN.ts 的 router 段里有 dashboard、analysis、devTool、password 等 key 没有任何对应路由——脚手架残留。搜到它们不要顺着找页面，那里没有页面。

第 2 步（只有 A 分支要走）：路由 → 组件，名字不对应

路由表在 src/router/index.ts:46-262（asyncRouterMap）。 五条 path 和目录名对不上，外加一条入口文件名例外，凭直觉猜必错：

最后一条最阴：目录名是对的，文件名不是 index.vue。你打开 views/Option/ 会看到一堆文件，入口是 Option.vue。全表在 路由定位速查卡，别背，用的时候查。

还有两条路由整段被注释掉了（/creator 与 /project， src/router/index.ts:142-159）。搜到它们时不要以为是自己没找对文件。

第 3 步：组件的 import 块就是一张分层地图

这是本课最省时间的一招。打开任何一个页面组件， 先不看模板、不看逻辑，只读 <script setup> 开头的 import 块——它直接告诉你这个页面会碰到哪几层，也就告诉你出问题时该怀疑谁。

拿资源工作台举例 （src/views/Workspace/index.vue:53-72）：

最后一行值得停一下。这是渲染进程，正常情况下它不该能 import 'node:http'。 它能，是因为主进程把渲染层的 Node 能力整个打开了 （electron/main/index.ts:47-51）。 这件事的完整后果是课 03 的主题； 现在你只需要知道：在 GameBox 里，「前端页面」可以直接读写你的磁盘。 定位时不要因为「这是前端」就排除文件系统问题。

第 4 步：进了 src/api/ 不等于就在发请求

到了 src/api/**，很多人默认「这里都是发 HTTP 请求的」。在这个项目里不是—— src/api/ 下的模块分成两类，看 import 块的第一行就能分清：

分流的实际意义：副作用模块出问题时，DevTools 的 Network 面板是空的。 在那里找证据会白找很久——本课的「替换」就是这种情况。

实战：追一次「替换」

现在走完开头那张截图。「替换」是硬编码文案，所以走 B 分支——rg 一步命中组件，不碰路由表。 全程五跳，每一跳都有行号。

五跳，全部靠 rg 和「跳转到定义」，不需要读懂任何一个函数的内部逻辑。 这就是 15 分钟定位的实际样子——它是机械的，不需要灵感。

第 ② 跳需要一点 Vue 模板知识：@click="…" 是绑定点击事件（相当于 onclick），v-for 是循环渲染，v-if 是条件渲染。定位阶段你只需要认得 @click——它是「界面元素 → 处理函数」之间那根线。 完整的模板语法在课 04 讲。

走到终点才看得见的两件事

第一件：这个「替换」在特定条件下会直接提交一次 SVN 删除。

要同时满足两个条件才会走到那里：

• 被替换的是目录型资源——extname(element) == '' （src/api/workspace/index.ts:763）；
• 目标目录已经存在——FS.existsSync(targetDir) （src/api/workspace/index.ts:770）。

if (FS.existsSync(targetDir)) {
  await SVN.svnDelete(targetDir)
  await SVN.svnCommit([targetDir])
}

注意提交的是什么：只有删除。 后面把新目录移进来的那几步（src/api/workspace/index.ts:774-781） 没有 svnAdd，也没有第二次 svnCommit。 所以准确的结论是：它可能已经把旧目录从仓库里删掉并提交了，但新内容只落在你本地。

这比「资源没变」严重得多——仓库里那份可能真的没了，而本地看起来是好的。 而且这一切不需要你去发布栈点任何按钮，和「所有提交都统一在游戏发布栈做」的直觉相反。

第二件：那句「更新成功」可能早于实际完成。

根因只有一处，就在 src/api/workspace/index.ts:759-760：

// await Promise.all(
select.map(async (element) => {
  …
  await SVN.svnDelete(targetDir)
  await SVN.svnCommit([targetDir])
  …
})
// )

map 里每个回调都是 async，各自返回一个 Promise；await Promise.all(…) 那两行被注释掉之后， 这组 Promise 没有任何人接住。replaceFile 本身是普通函数，它会一路执行到 src/api/workspace/index.ts:784 的 return true 并立刻返回，而目录分支里的 await SVN.svnDelete(…) 才刚排上队。

要把因果说准：调用方 src/views/Workspace/Components/ViewCard.vue:326 确实没有 await replaceRes(data)，但 replaceRes 内部并没有 await， 它是同步跑到弹窗那一步的——所以少写这个 await 不是本次现象的原因。 真正的原因只有上面那一处。定位的价值就在这里：能把「哪一行导致了这个现象」和「哪一行只是写得不好」分开。

于是 src/views/Workspace/Components/ViewCard.vue:278 的 typeof result == 'boolean' 立刻拿到 true，此时目录分支里的 SVN 操作和文件移动可能一步都还没做完， 弹窗已经写着「更新成功」了。

这就解释了截图里的现象。注意我们没有修任何东西——定位的产物是一个带证据的结论，不是一个补丁。 能把话说到这个份上（哪一行是根因、哪一行只是碍眼、后果具体是什么）， 你才知道该改哪一层、回归范围有多大。

权限：不要去路由表里找

「为什么他看不到这个按钮 / 他点进去提示无权限」是接手后最常收到的问题之一。 在 GameBox 里，路由表不是答案。

src/store/modules/permission.ts:36-56 的 generateRoutes() 做的全部事情是：cloneDeep(asyncRouterMap) 再拼一条 404 兜底路由。一行权限过滤都没有，也没有任何后端菜单下发。 所有登录用户拿到的路由表完全一样。

真正的限制分散在两类地方。先看守卫这一类：

再看页面内这一类，它没有统一写法。 「看不到按钮」很容易被想当然地归给 v-if，但这个项目里至少有四种：

所以收到「某人看不到 / 点不动某个按钮」，正确动作是：先定位到那个按钮所在的组件，然后在组件里搜这一串关键词—— userInfo、Privilege、user_type、v-if、v-show、:disabled、&&。 去翻路由表是白费时间。

项目里还注册了一个 v-hasPermi 指令 （src/directives/permission/hasPermi.ts:43）。 但全项目除了这处注册，没有任何一个地方使用它——脚手架残留，搜到了不用顺藤摸瓜。

顺带解开课 01 留的一个扣

课 01 说 sessionStorage.currentRouter「不等于地址栏」。 现在你有背景知识了：GM 是弹窗，不是路由页面 （在 src/App.vue:12 直接引入，地址栏不变）。 但 service.ts 要靠一个「当前在哪」的标识来选接口环境， 弹窗又没有自己的路由——所以只能人为写一个虚拟值 '/GM' 进去。 这个设计的代价是：定位时不能反过来用 currentRouter 推断用户在哪个页面。

这个实现值不值得模仿

检索练习

同样先从记忆里取。

去真机上验证（约 15 分钟）

读到这里你只是「看过」了。下面每一步都要在跑起来的应用里做完。 源码证明当前实现是怎么写的，真机证明用户实际看到什么——两者都是证据。 如果你在真机上看到的和这一课写的不一致， 那更值得记下来：多半是我漏了一个条件分支。

cd ~/Projects/works/gameboxclient
npm run dev

• 走一次四步法。随便挑一个你在界面上看得见的按钮或提示文字， 用 rg "那句中文" src 开始，走到 src/api/** 或 src/utils/extend/** 为止。计时，看看实际花了几分钟。
• 验证路由是动态加进去的。在 src/permission.ts:118 那行 addRoute() 上打断点，然后登录。 断点停下时在 Sources 面板的作用域里看 permissionStore.getAddRouters 的长度， 再单步过去看 router.getRoutes().length 怎么变 ——路由是在这里逐条补进去的。 注意不能在 Console 里直接敲 $router：这个项目没有把 router 挂到 window 上，只有在断点的作用域里才拿得到它。
• 数一次导航经过了几个 next()。 在 beforeEach（src/permission.ts:99）和 docView、uiView 里每一处 next(…) 上都打断点，然后切一次页面， 看单次导航实际停了几次——这是验证「next() 被多次调用」最直接的方式。 不要靠 Console 里的 放行: 日志数数： 它只在首次动态加路由那一次打印，之后的导航会在 src/permission.ts:112-114 提前 return，根本走不到那行 console.log。
• 确认 hash 模式。看地址栏是不是 #/workspace 这种形式，切页面时井号后面跟着变。
• 不要真的去点「替换」。替换目录型资源时它会对 SVN 发起真实的删除提交 （src/api/workspace/index.ts:771-772）， 而学习任务里「哪些工作副本可以安全操作」 这一条还没有得到确认。 这一课的替换链路只做代码追踪，不真跑。