# 问题排查记录：权限平台默认值与开发服务 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. 除首页外，进入其他页面后刷新浏览器会出现页面空白。

---

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

### 现象

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

```js
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` 中将：

```js
store.dispatch('user/buttonPermissions')
```

修改为：

```js
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` 中继续保留并确认：

```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` 中刷新后的初始化流程改为严格串行：

```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()`，而是使用：

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

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

### 处理结果

调整后：

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

### 涉及文件

- `src/permission.js`

---

## 二、开发服务 `Network: unavailable`

### 现象

执行 `npm run dev` 后输出类似：

```txt
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` 中增加：

```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 变化，或当前网络环境特殊，也可以临时手动指定：

```powershell
$env:DEV_SERVER_PUBLIC_IP='192.168.0.115'
npm run dev
```

或：

```powershell
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. 涉及动态路由的后台项目，刷新页面时必须保证“菜单加载 -> 路由注入 -> 再放行当前路由”是串行完成的，否则深层页面极易出现刷新白屏。