问题排查
39-白模导演台 · 2026-10-12 · 2.1 KB
白模的问题九成是三类：服务没起、端口被占、产物缺失 ⇒ 先看状态灯，再按现象查。
本专题手工维护（2026-10-12 建）；⚠ 报错文案以应用当前版本为准（本页快照 2026-10-12）。
一、先按这个顺序查（三步定因）
① 看状态灯：未启动 / 端口被占 / 产物缺失 ⇒ 灯上直接写着原因 ✓
② 看编辑器是否「已连宿主」：没连上 ⇒ 服务在跑但页面没握上手（§三）
③ 看是不是"你改过地址"：改过 ⇒ 起停按钮不参与 ⇒ 那个地址得你自己保证可达 ✓
二、按现象查（对照表）
| 现象 | 多半原因 | 处置 | |
|---|---|---|---|
| 标签打开后一片空 / 加载不出 | 服务没起 | 点 「启动白模」（现在打开标签会自动起一次 ✓） | |
| 状态灯 端口被占用 | 8890 上被别的程序占了 | `netstat -ano \ | findstr :8890` 找占用者 ⇒ 结束它 ⇒ 再点启动 ✓ |
| 状态灯 产物缺失 | 这个安装包里没带白模产物 | 见 §四 ✓ | |
| 状态灯 启动出错 | 起服务失败（附原因） | 看提示原文（多为端口 / 权限）；让出端口后重试 ✓ | |
| 状态灯 外部已在运行 | 那是你自己起的服务 | 不是故障：应用直接内嵌它，也不会关它 ✓ | |
| 「未连上（编辑器没在跑？）」 | 服务在跑，但页面 6 秒内没握手 | 见 §三 ✓ | |
| 编辑器里点选目录 / 读写文件没反应或失败 | 跨源限制 + 宿主通道 | 见 §五 ✓ | |
| 改了地址后什么都连不上 | 改到了不可达的自定义地址 | 改回默认地址，或先保证那个地址能打开 ✓ | |
| 原来的工程不见了 | 地址来源变了（localhost ↔ 127.0.0.1 / 换端口） | 改回原来源即可看见（localStorage 按来源隔离）✓ | |
| 老版本里没有"代选目录" | 宿主版本较老 | 升级应用，或用 「在新窗口打开」 ✓ |
三、「没连上白模编辑器」（等 6 秒未握手）
这条提示意味着：服务可能在跑，但内嵌页面没握上手。按提示逐条排：
- 服务真的在跑吗 ⇒ 状态灯是否为"已启动 / 外部已在运行" ✓
- 看控制台（F12） ⇒ 是否出现
Refused to frame …之类的被拦信息 ✓ - 点「重试」 ⇒ 重新加载内嵌页 ✓
- 仍不行 ⇒ 用 「在新窗口打开」 走独立窗口（能确认到底是"白模本身"还是"内嵌"的问题 ✓）
四、「产物缺失」（只有这一种要出包侧处理）
提示原文形如：
随包产物不在（…/index.html）⇒ 出包前跑一次 npm run pack:whitemodel（它把同级项目 WhiteModel 的 dist 同步进来 ✓）
| 你是谁 | 怎么办 |
|---|---|
| 普通用户 | 说明这个安装包没带白模 ⇒ 升级到带白模的正式包 ✓ |
| 出包 / 维护者 | 出包前跑一次那步同步（同步会把 sourcemap 剔掉）⇒ 再出包 ✓ |
⇒ 判定要点：白模从某版起重为"随包" ⇒ 老包没有它是正常的，不必怀疑环境 ✓
五、导入 / 导出失败（跨源 + 宿主通道）
| 现象 | 含义 | 处置 |
|---|---|---|
| 点导入后弹的是应用这边的选目录 | 设计如此（跨源限制 ⇒ 走宿主通道） | 按提示选即可 ✓ |
| 提示「这个宿主版本没有接『代选目录』这条通道」 | 应用版本较老 | 升级应用，或 「在新窗口打开」 ✓ |
| 选目录时报"被环境挡住了" | 系统/环境层面拦了文件对话框 | 换成本机正常路径重试；必要时改用独立窗口 ✓ |
⚠ 越界与缺文件（编辑器/宿主读文件时的两类提示）：越界访问会被直接拒绝（保护你的机器），文件不存在会说没有这个文件 ⇒ 都不是"白模坏了"，是路径没给对 ✓
六、要报障时，把这四样一起给
① 状态灯原话（例如"端口 8890 被占用"）+ 截图
② 面板地址（默认那条 or 你改成了什么）
③ 当时那一步在做什么（启动 / 导入 / 导出 / 打开标签）
④ 控制台里的报错原文（F12 → Console，尤其含 Refused / 握手 / 服务 的行）✓
⇒ 这四样能覆盖 §二表里绝大多数分支，基本一轮就能定位 ✓
来源：E:/workbuddyProj/unlimitCanvas/ai_manual/white_model/04-问题排查.md