aslan-admin/docs/问题排查记录-权限平台与开发服务地址.md

问题排查记录：权限平台默认值与开发服务 Network 地址

记录时间

• 2026-04

背景

本次排查涉及四个独立但连续出现的问题：

1. 页面初始化时，this.permissionsSysOriginPlatforms[0] 偶发拿不到，导致默认平台没有赋值，后续 renderData(true) 不执行。
2. 本地执行 npm run dev 后，控制台一直显示 Network: unavailable，但同机器的其他项目可以正常显示类似 http://192.168.0.115:5173/ 的局域网访问地址。
3. src/views/user/user-table/index.vue 页面刷新后，搜索栏中的系统默认选项为空，列表也没有自动刷出；只有再次手动点击搜索后，默认系统和列表才恢复正常。
4. 除首页外，进入其他页面后刷新浏览器会出现页面空白。

---

一、权限平台默认值偶发为空

现象

页面中存在如下初始化逻辑：

const querySystem = this.permissionsSysOriginPlatforms[0];
if (!querySystem) {
  return;
}
that.listQuery.sysOrigins = [querySystem.value];
that.renderData(true);

当 this.permissionsSysOriginPlatforms[0] 为空时，页面会直接返回，默认查询条件与首屏数据都不会初始化。

结论

permissionsSysOriginPlatforms 不是接口直接返回的平台数组，而是：

1. 按钮权限接口先返回权限别名列表。
2. 前端再用本地写死的 sysOriginPlatforms 常量进行过滤。
3. 过滤结果再写入 Vuex，页面最终通过 getter 读取。

也就是说：

• 平台候选项来源于前端常量。
• 当前用户能拿到哪些平台，取决于按钮权限接口返回的权限别名。

关键代码链路

• 页面读取位置：src/views/user/user-table/index.vue
• getter 映射位置：src/store/getters.js
• Vuex 组装位置：src/store/modules/user.js
• 平台常量定义：src/constant/origin.js
• 按钮权限接口：src/api/ops-system.js

根因

根因是时序问题，不是页面本地代码本身写错：

1. 路由守卫中会调用 store.dispatch('user/buttonPermissions')。
2. 但原逻辑没有 await 这个异步请求。
3. 页面已经进入并执行 created() 时，权限数据可能还没回填到 Vuex。
4. 于是 this.permissionsSysOriginPlatforms[0] 偶发为空。

另外还有一个补充前提：

• 当前前端常量里只有 ATYOU 一个系统平台，并且依赖权限 query:atyou。
• 如果接口没有返回这个权限，过滤后数组本身也会为空。

已做处理

已在 src/permission.js 中将：

store.dispatch('user/buttonPermissions')

修改为：

await store.dispatch('user/buttonPermissions')

处理结果

调整后，路由放行前会先等待按钮权限加载完成，页面 created() 再读取 permissionsSysOriginPlatforms 时，不会再因为异步竞争导致首项为空。

后续建议

• 若后续仍出现空数组，需要优先检查接口返回是否包含 query:atyou。
• 如果页面还需要进一步增强健壮性，可以在页面侧增加 watcher 或兜底默认逻辑，但当前首先应保证路由阶段权限已完成回填。

---

三、user-table 刷新后系统默认项为空

现象

在 src/views/user/user-table/index.vue 页面中：

• 首次进入时有概率搜索栏中的“系统”默认值为空。
• 刷新页面后更容易复现。
• 首屏列表没有自动加载。
• 用户手动点击一次搜索后，系统默认选项和列表又会恢复正常。

根因

这个问题本质上还是权限平台数据的异步时序问题，但触发点更具体：

1. 页面在 created() 中直接读取 this.permissionsSysOriginPlatforms[0]。
2. 如果刷新时权限平台数据尚未回填，querySystem 就为空。
3. 原逻辑在判空后会直接 return，导致：
   • listQuery.sysOrigins 没有默认值。
   • renderData(true) 不执行。
   • 页面其余初始化流程也被提前中断。
4. 等到权限数据后续回填后，页面没有额外 watcher 继续补初始化，所以只能依赖用户再次手动搜索。

已做处理

本次针对这个页面做了两层修复：

1. 在 src/permission.js 中继续保留并确认：

await store.dispatch('user/buttonPermissions')

确保路由放行前优先等待按钮权限加载完成。

2. 在 src/views/user/user-table/index.vue 中增加页面级兜底：

• 新增 hasInitializedSysOrigin 标记，避免重复初始化。
• 监听 permissionsSysOriginPlatforms。
• 当权限平台列表第一次变为有值时：
  • 自动取第一项写入 listQuery.sysOrigins
  • 自动执行 renderData(true)

3. 去掉 created() 中“拿不到系统平台就直接 return”的初始化方式，避免首屏逻辑因为一次空值被永久跳过。

处理结果

调整后，即使刷新页面时 permissionsSysOriginPlatforms 比页面创建更晚回填：

• 搜索栏系统默认值也会在权限到达后自动补上。
• 首屏列表会自动触发加载。
• 不再需要用户手动点击搜索来恢复页面状态。

涉及文件

• src/permission.js
• src/views/user/user-table/index.vue

---

四、非首页刷新后页面白屏

现象

• 首页通常可以正常刷新。
• 进入其他菜单页后，直接刷新浏览器会出现页面空白。
• 这类问题在二级、三级动态路由页面上更容易复现。

根因

问题出在刷新时的动态路由注入时序：

1. 刷新页面后，应用会重新进入 src/permission.js 中的路由守卫。
2. 当前项目的很多页面并不是一开始就存在于静态路由中，而是依赖 getMenus() 返回菜单后再通过 router.addRoutes() 动态注入。
3. 原逻辑中虽然调用了 getMenus()，但没有等待菜单加载和动态路由注入真正完成，就提前执行了 next()。
4. 当用户刷新的是非首页深层路由时，当前目标路由可能还没注册到 router 中，于是会出现匹配失败，最终表现为空白页。

首页之所以通常不受影响，是因为首页对应的是默认静态路由，不依赖后续动态注入。

已做处理

已将 src/permission.js 中刷新后的初始化流程改为严格串行：

await store.dispatch('user/getInfo')
const grantRouters = await store.dispatch('user/getMenus')
if (grantRouters && grantRouters.length > 0) {
  router.addRoutes(grantRouters)
}
store.dispatch('user/getUserDashboard')
await store.dispatch('user/buttonPermissions')
next({ ...to, replace: true })

修复要点

这次修复包含两个关键点：

1. 先等待 getMenus() 返回，再执行 router.addRoutes(grantRouters)。
2. 动态路由注入完成后，不再直接 next()，而是使用：

next({ ...to, replace: true })

这样会用当前目标地址重新进入一次匹配流程，确保刚注入的动态路由能够正确命中当前页面。

处理结果

调整后：

• 刷新非首页页面时，不会再因为动态路由尚未注册而白屏。
• 当前页面会在动态路由注入完成后重新匹配并正常进入。

涉及文件

• src/permission.js

---

二、开发服务 Network: unavailable

现象

执行 npm run dev 后输出类似：

App running at:
  - Local:   http://localhost:9528
  - Network: unavailable

但同一台机器上的其他项目可以正常显示局域网访问地址。

初步排查结论

这不是项目无法启动，也不是没有局域网 IP，而是 Vue CLI 选错了网卡。

通过系统网络信息确认：

• 当前机器存在可用私网地址：192.168.0.115
• 同时还存在一个虚拟网卡地址：26.26.26.1

根因

项目使用的是较老版本的 @vue/cli-service 3.6.0。

该版本在生成 Network 地址时，会在内部调用 address.ip() 取一个 IPv4 地址，然后只接受以下私网地址范围：

• 10.x.x.x
• 172.16.x.x 到 172.31.x.x
• 192.168.x.x

如果拿到的不是私网地址，就会直接将 Network 显示为 unavailable。

本次机器环境中，Vue CLI 优先拿到的是虚拟网卡 26.26.26.1，由于它不属于私网范围，因此被直接丢弃，最终控制台显示 Network: unavailable。

关键代码位置

• 输出逻辑：node_modules/@vue/cli-service/lib/commands/serve.js
• 局域网地址选择逻辑：node_modules/@vue/cli-service/lib/util/prepareURLs.js

已尝试处理

第一步

先在 vue.config.js 中增加：

host: '0.0.0.0'

目的：

• 让 dev server 监听所有网卡，而不是只监听本机回环地址。

结果：

• 监听范围已放开。
• 但 Network 仍然显示 unavailable。
• 说明问题不在监听地址，而在 Vue CLI 的网卡识别逻辑。

第二步

在 vue.config.js 中新增自定义 LAN IP 选择逻辑，替代 Vue CLI 默认的“随便取一个 IPv4”的方式。

处理思路：

1. 使用 os.networkInterfaces() 枚举网卡。
2. 只保留私网 IPv4。
3. 优先选择 WLAN / Wi-Fi / Ethernet / 以太网 这类常见真实网卡。
4. 排除 TAP / VPN / Virtual / VMware / Hyper-V / Docker / vEthernet 等虚拟网卡。
5. 将最终结果写入 devServer.public。

当前配置结果

vue.config.js 已调整为：

• host: '0.0.0.0'
• public: lanIp ? \${lanIp}:${port}` : undefined`

并增加了自动识别私网地址的辅助函数。

处理结果

此修改的目的不是单纯让服务“能访问”，而是：

1. 明确让服务监听所有网卡。
2. 明确告诉旧版 Vue CLI 应该向外公布哪个局域网地址。
3. 避免其误选虚拟网卡后把 Network 判成 unavailable。

备用方案

如果后续本机 IP 变化，或当前网络环境特殊，也可以临时手动指定：

$env:DEV_SERVER_PUBLIC_IP='192.168.0.115'
npm run dev

或：

npm run dev -- --public 192.168.0.115:9528

---

本次涉及的改动文件

• src/permission.js
• src/views/user/user-table/index.vue
• vue.config.js
• docs/问题排查记录-权限平台与开发服务地址.md

本次经验总结

1. 页面里出现“偶发空值”时，优先检查数据来源是不是异步回填，而不是只盯页面局部逻辑。
2. permissionsSysOriginPlatforms 这类字段要区分“候选项来源”和“最终权限结果来源”。
3. 老版本 Vue CLI 对网卡选择并不稳定，机器上存在 VPN、TAP、虚拟网卡时，Network: unavailable 往往是地址识别问题，不代表 dev server 本身不可用。
4. 对局域网访问有明确需求的项目，最好显式配置 devServer.host 与 devServer.public，不要完全依赖工具链自动推断。
5. 对首屏依赖异步权限数据的页面，不应只在 created() 中做一次性读取；更稳妥的方式是配合 watcher 或显式初始化状态，在权限到达后自动补齐默认值与首屏请求。
6. 涉及动态路由的后台项目，刷新页面时必须保证“菜单加载 -> 路由注入 -> 再放行当前路由”是串行完成的，否则深层页面极易出现刷新白屏。