Forráskód Böngészése

fix(preview): 断网时预览显示浏览器错误页 + 重新加载失效

## 问题 1:断网时预览显示 Chrome 原生错误页

断网后点开 HTML 预览,显示:
  网页无法打开 / net::ERR_NAME_NOT_RESOLVED

而不是 App 自己的错误提示,与设计语言完全不符。

根因:断网时 iframe 仍会**正常触发 load 事件**(浏览器渲染自己的错误页),
onFrameLoad() 把「加载失败」当成了成功,清掉超时定时器,frameStalled 永不置位。

修复(第三次尝试才成功,前两次假设都被真机推翻):
  ① 同源能读到内容 → 检查是否含 ERR_* / 「网页无法打开」
  ② 跨域读不到 → 用 HEAD 探测**目标文件本身**
     · 断网 → 抛异常 → 判失败
     · 文件 404 → res.ok=false → 判失败
     · 正常 → 判成功

调试过程:
  尝试 1 用 navigator.onLine → ❌ 飞行模式下仍返回 true(MIUI)
  尝试 2 探测 server.fmode.cn → ❌ 该地址 HEAD 挂起 4 秒,在线时也误判
  尝试 3 探测目标文件本身 → ✅ 语义最准确

## 问题 2:点「重新加载」后错误提示不消失,iframe 跳到 App 首页

根因:retryFrame() 只做 setAttribute('src',''),清空后 Angular 的属性绑定
没有变化不会重新写回,iframe 落在了 https://localhost/。

修复:about:blank → 强制回流 → 写回目标地址(带 _r 时间戳破缓存)。

这个 bug 在 CORS 修复前就存在,只是当时文件根本加载不出来,没人发现。

## 真机验证(小米 M2102K1AC / Android 14)

| 场景 | 结果 |
|---|---|
| 在线打开预览 | ✅ 内容正常渲染,不再误报错误 |
| 断网打开预览 | ✅ 显示 App 错误提示 + 两个出口按钮 |
| 恢复网络后重新加载 | ✅ 错误消失、内容渲染、src 带 _r= 破缓存 |

## 文档

- 2026-11-18-全面回归测试记录:A/C/F/G 组逐项结果 + 本问题的完整调试过程
- 平台与容器侧待办需求-20261118:多值 CORS、/api-platform/ 反代、
  MEDIA 漏生成事件、后台推送(暂不做)四项,含复现命令与验收标准

Co-Authored-By: Claude Code <noreply@anthropic.com>
Huccct 1 órája
szülő
commit
f68744a662

+ 145 - 0
docs/00-tracking/2026-11-18-全面回归测试记录.md

@@ -0,0 +1,145 @@
+# 2026-11-18 全面回归测试记录
+
+> 设备:小米 M2102K1AC / Android 14(API 34)
+> APK:11-18 10:50 构建,含 s3 CORS 修复 + pdfjs worker 构建修复
+> 统计口径:用户消息 `app-m-msg .m-msg-me` · 容器回复 `app-assistant-turn` · 文件卡片 `button.file-tile`
+
+---
+
+## 一、测试结果总表
+
+### A. 基础启动与导航
+
+| # | 项目 | 结果 | 说明 |
+|---|---|---|---|
+| A1 | 冷启动进会话列表 | ✅ | 无白屏、无报错,8574 字符内容完整渲染 |
+| A2 | 四个 Tab 切换 | ✅ | 会话/通讯录/工作台/我的 全部正确跳转并渲染 |
+| A3 | 状态栏不遮挡 | ✅ | `--mob-safe-top: 39px`,顶栏完整可见 |
+| A4 | 底部 TabBar 安全区 | ✅ | 截图确认未被手势条压住 |
+| A5 | 物理返回键 | ✅ | 会话 → 列表正确返回,不退出不白屏 |
+
+### C. 文件预览(CORS 修复后重点验证)
+
+| # | 项目 | 结果 | 说明 |
+|---|---|---|---|
+| C1 | PDF 预览 | ✅ | **核心链路通过**:1 页 / 595×842 / 74ms / v4.10.38,**无版本不匹配报错** |
+| C2 | Word 预览 | ✅ | 表格内容完整渲染(华东区/销售额均可读) |
+| C4 | HTML 预览 | ✅ | 正常渲染,工具栏 8 个按钮齐全 |
+| C7 | 工具栏按钮 | ✅ | 重新加载/缩小/放大 均可用,预览保持打开 |
+| C8 | 不弹 tooltip | ✅ | 连点三个按钮,可见 tooltip **数量为 0** |
+
+### F. 异常处理
+
+| # | 项目 | 结果 | 说明 |
+|---|---|---|---|
+| F1 | 断网提示 | ✅ | 顶栏「网络已断开」+ 连接提示条 |
+| F2 | 断网发送 | ✅ | 显示「发送失败,重试」 |
+| F3 | 恢复后重试 | ✅ | 重试成功,失败态消失 |
+| F4 | 断网时预览 | ❌ | **显示浏览器原生错误页**,详见问题 1 |
+
+### G. 样式与主题
+
+| # | 项目 | 结果 | 说明 |
+|---|---|---|---|
+| G1 | 亮色主题 | ✅ | 背景 `rgb(242,243,245)` / 文字 `rgb(32,33,36)`,对比度 ~14:1 |
+| G2 | 暗色主题 | ✅ | 背景 `rgb(27,26,34)` / 文字 `rgb(242,240,248)`,对比度 ~15:1 |
+| G3 | 主题色切换 | ✅ | 4 种配色均可切换,TabBar 激活色同步变化 |
+| G5 | 长标题截断 | ✅ | `ellipsis + overflow:hidden + nowrap` |
+
+### D. 文件卡片与对账
+
+| # | 项目 | 结果 | 说明 |
+|---|---|---|---|
+| D3 | 缺失提示 | ✅ | 「还有 1 个文件未收到」正确显示 |
+
+---
+
+## 二、发现的问题
+
+### 问题 1:断网时预览显示浏览器原生错误页(已修复)
+
+| 项 | 内容 |
+|---|---|
+| **严重度** | 🟡 中(体验问题,不影响功能恢复) |
+| **复现** | 断网 → 点开 HTML 文件预览 |
+| **实际表现** | 显示 Chrome 原生错误页:<br>`网页无法打开`<br>`net::ERR_NAME_NOT_RESOLVED` |
+| **预期表现** | App 自己的错误提示 + 重试按钮 |
+| **根因** | 断网时 iframe 会**正常触发 `load` 事件**(浏览器渲染自己的错误页),于是 `onFrameLoad()` 把「加载失败」当成了成功,清掉超时定时器,`frameStalled` 永远不会置位 |
+| **修复(第三次尝试才成功)** | `onFrameLoad()` → `verifyFrameLoaded()`:<br>① 同源能读到内容 → 检查是否含 `ERR_*` / 「网页无法打开」<br>② 跨域读不到 → 用 `HEAD` **探测目标文件本身**<br>  · 断网 → 抛异常 → 判失败<br>  · 文件 404 → `res.ok=false` → 判失败<br>  · 正常 → 判成功 |
+| **同时修复的隐藏 bug** | `retryFrame()` 原来只做 `setAttribute('src','')`,清空后**没有写回目标地址**,iframe 落到了 `https://localhost/`(App 首页),且错误提示不消失。改为 `about:blank` → 强制回流 → 写回目标地址(带 `_r` 时间戳破缓存) |
+| **文案改进** | 「文件加载失败。请检查网络连接后重试;若网络正常,可能是文件地址已失效。」 |
+| **状态** | ✅ 已修复,真机三场景全部验证通过 |
+
+#### 调试过程(三个被推翻的假设)
+
+| 尝试 | 假设 | 真机实测结果 |
+|---|---|---|
+| 1 | 用 `navigator.onLine` 判断断网 | ❌ 飞行模式下仍返回 `true`,`connection.effectiveType` 还是 `4g` |
+| 2 | 探测 `server.fmode.cn` HEAD | ❌ 该地址**挂起,4 秒超时**,导致**在线时也误报错误** |
+| 3 | 探测**目标文件本身** | ✅ 语义最准确,且顺带覆盖「文件已失效」场景 |
+
+> 教训:`navigator.onLine` 在 MIUI 的 WebView 里不可信;
+> 判断网络可达性必须探**远端**且**响应快**的地址,最好就是目标本身。
+
+#### 真机验证(三场景)
+
+| 场景 | 结果 |
+|---|---|
+| **在线**打开预览 | ✅ 内容正常渲染,`stall: false`(不再误报) |
+| **断网**打开预览 | ✅ 显示 App 错误提示 + 「重新加载」「在新标签打开」 |
+| 恢复网络后点**重新加载** | ✅ 错误消失、内容渲染、iframe src 带 `_r=` 破缓存参数 |
+
+---
+
+## 三、已验证正常的项目(详情)
+
+### 文件预览链路(CORS 修复的最终成果)
+
+| 文件 | fetch 结果 |
+|---|---|
+| PDF | ✅ 3,607 字节,pdfjs 解析 1 页 |
+| DOCX | ✅ 37,341 字节,表格渲染正确 |
+| XLSX | ✅ 5,102 字节 |
+| HTML | ✅ 2,048 字节 |
+
+### 断网异常处理
+
+```
+断网 30 秒 → 顶栏「lj-test · 网络已断开」+ 底部「连接已断开,点击重连」
+发送消息 → 「发送失败,重试」按钮
+恢复网络 → 点重试 → 成功,失败态消失
+```
+
+### 主题系统
+
+| 主题 | 背景 | 文字 | 对比度 |
+|---|---|---|---|
+| 亮色 | `rgb(242,243,245)` | `rgb(32,33,36)` | ~14:1 ✅ |
+| 暗色 | `rgb(27,26,34)` | `rgb(242,240,248)` | ~15:1 ✅ |
+
+均超过 WCAG AA 要求(正文 4.5:1)。
+
+---
+
+## 四、未测项(需特定条件)
+
+| 项目 | 原因 |
+|---|---|
+| B4 快速连点防重复 | 11-16 已测通过,本轮未重复 |
+| B5 草稿隔离 | 11-16 已测通过,本轮未重复 |
+| E 组外部分享 | 11-16 已测通过,本轮未重复 |
+| C3 Excel 预览 | 会话内无 xlsx 卡片,仅验证了 fetch 可达 |
+| C5/C6 图片/Markdown | 会话内无对应文件 |
+
+---
+
+## 五、结论
+
+**本轮修复验证通过**:
+
+1. ✅ **s3 CORS 已生效** —— 四种文件类型全部可 fetch,pdfjs 解析无报错
+2. ✅ **pdfjs worker 版本正确** —— 4.10.38,无 6.4.x 残留
+3. ✅ **断网异常处理完整** —— 提示、失败反馈、重试恢复全链路正常
+4. ✅ **UI/样式/主题正确** —— 安全区、对比度、主题切换、标题截断均正常
+
+**新发现 1 个问题**:断网时预览显示浏览器原生错误页(体验问题,不阻断)。

+ 293 - 0
docs/03-interface/平台与容器侧待办需求-20261118.md

@@ -0,0 +1,293 @@
+# 平台侧待办需求(3 项)
+
+> 2026-11-18 整理。**每一项都含可复现证据、根因、修改点、验收命令。**
+> 后台推送经用户裁决**暂不做**,仅记录在案。
+
+---
+
+## 一、多值 CORS:`/api/apig/message` 对 `https://localhost` 返回两个 ACAO 头
+
+### 严重度与状态
+
+| 项 | 内容 |
+|---|---|
+| 严重度 | 🟡 中(App 已用云函数代理绕过,但浏览器直连时失败) |
+| 责任方 | **平台**(网关 / nginx / Express 三者之一重复加头) |
+| 状态 | ❌ **未修复,约 50% 概率触发** |
+
+### 复现(100% 可复现)
+
+```bash
+# 连续请求,约一半会返回 2 个 ACAO 头
+for i in $(seq 1 10); do
+  n=$(curl -sS -I -H "Origin: https://localhost" \
+      "https://server.fmode.cn/api/apig/message" 2>/dev/null \
+      | grep -ci "^access-control-allow-origin")
+  echo "第 $i 次: $n 个"
+done
+```
+
+实测输出(2026-11-18):
+```
+第1次: 1    第2次: 2 ❌   第3次: 1    第4次: 2 ❌   第5次: 1
+第6次: 1    第7次: 2 ❌   第8次: 1    第9次: 2 ❌   第10次: 2 ❌
+→ 10 次中 5 次异常
+```
+
+### 异常时的完整响应头
+
+```http
+HTTP/1.1 200 OK
+server: nginx
+x-powered-by: Express
+access-control-allow-origin: https://localhost    ← ① 某层回显了具体 origin
+x-content-type-options: nosniff
+access-control-allow-origin: *                    ← ② 另一层又加了 *
+```
+
+**正常时**只有 `access-control-allow-origin: *`。
+
+### 触发条件(重要)
+
+| Origin | 结果 |
+|---|---|
+| `https://ai.fmode.cn` | ✅ 1 个(正常) |
+| `https://fmode.cn` | ✅ 1 个(正常) |
+| **`https://localhost`(App 内 WebView)** | ❌ **约 50% 返回 2 个** |
+
+说明:**某个中间层对「不在白名单的 origin」做了动态回显**,而下游又无条件加了 `*`。
+
+### 根因推断
+
+典型的两层叠加:
+
+```
+nginx / 网关层:  if origin not in whitelist → add_header ACAO $http_origin
+Express 层:      res.setHeader('Access-Control-Allow-Origin', '*')
+                  ↓
+              两者都输出 → 两个头
+```
+
+### 修改点(二选一)
+
+**方案 A(推荐):把 `https://localhost` 纳入白名单**
+
+在网关/nginx 的 CORS 白名单里加上 `https://localhost`(App 的固定 origin,
+见 `capacitor.config.ts` 锁定 `hostname: localhost` + `scheme: https`)。
+
+但**仍要确保只输出一次** —— 白名单命中后就不应再叠加 `*`。
+
+**方案 B:下游不再无条件加 `*`**
+
+让 Express 信任上游已设置的头,只在**未设置时**才补:
+
+```js
+if (!res.getHeader('Access-Control-Allow-Origin')) {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+}
+```
+
+### 验收标准
+
+```bash
+# 期望:10 次全部输出 1
+for i in $(seq 1 10); do
+  n=$(curl -sS -I -H "Origin: https://localhost" \
+      "https://server.fmode.cn/api/apig/message" 2>/dev/null \
+      | grep -ci "^access-control-allow-origin")
+  [ "$n" -eq 1 ] || echo "❌ 第 $i 次: $n 个"
+done
+echo "全部通过(无 ❌ 输出)"
+```
+
+同时用 AI 平台域名验证不受影响:
+```bash
+curl -sS -I -H "Origin: https://ai.fmode.cn" "https://server.fmode.cn/api/apig/message" \
+  | grep -ci "^access-control-allow-origin"   # 应为 1
+```
+
+### App 侧现状
+
+`fmode-login-proxy` 云函数(`zpus2KjtFH`)已代理登录链路,绕过该问题。
+**平台修复后可以去掉这层代理**,减少一次中转。
+
+---
+
+## 二、`ai.fmode.cn` 缺少 `/api-platform/**` 反向代理
+
+### 严重度与状态
+
+| 项 | 内容 |
+|---|---|
+| 严重度 | 🟢 低(**有回落机制,功能不中断**) |
+| 责任方 | 平台/运维(CDN 回源或 nginx 配置) |
+| 状态 | ❌ 未配置 |
+
+### 现象
+
+浏览器控制台每次打开都出现:
+```
+[PlatformProxy] /api-platform/ 未转发到平台(x-powered-by=空),回落直连 server.fmode.cn
+GET https://ai.fmode.cn/api-platform/api/zzz-fmode-probe 404 (Not Found)
+```
+
+### 判断方法(看 404 的 Server 头)
+
+```bash
+# 未转发 → Server: openresty + X-CCDN-*(落在 OBS 静态托管上)
+curl -sS -I https://ai.fmode.cn/api-platform/api/probe-xyz | grep -iE "server|x-powered-by"
+
+# 转发正常 → Server: nginx + x-powered-by: Express
+curl -sS -I https://server.fmode.cn/api/probe-xyz | grep -iE "server|x-powered-by"
+```
+
+实测(2026-11-18):
+
+| 请求 | Server 头 | 结论 |
+|---|---|---|
+| `ai.fmode.cn/api-platform/...` | `openresty` + `X-CCDN-*` | ❌ 落在 OBS |
+| `server.fmode.cn/api/...` | `nginx` + `x-powered-by: Express` | ✅ 平台真实响应 |
+
+### 影响
+
+| 方面 | 影响 |
+|---|---|
+| **功能** | ⚠️ 不中断。`platform-proxy.service.ts` 探测失败后回落直连 `server.fmode.cn` |
+| **控制台** | 每次多一个 404,干扰排查真问题 |
+| **CORS** | 回落直连时仍会撞上一、的多值 CORS |
+| **App** | 无影响(`isNativeApp()` 分支直接跳过探测) |
+
+### 修改点
+
+在 `ai.fmode.cn` 的**回源层**(华为云 CDN 的「动态加速」或源站 nginx)加:
+
+```nginx
+location /api-platform/ {
+    proxy_pass https://server.fmode.cn/api/;
+    proxy_set_header Host server.fmode.cn;
+    proxy_ssl_server_name on;
+}
+```
+
+> ⚠️ **不要在这里再加 `Access-Control-Allow-Origin`**。
+> 同源代理后浏览器不再做跨域检查,重复添加会产生**多值 ACAO**,
+> 反而被浏览器整体拒绝(正是问题一的成因)。
+
+### 验收标准
+
+```bash
+curl -sS -I https://ai.fmode.cn/api-platform/api/probe-xyz | grep -i "x-powered-by"
+# 期望输出:x-powered-by: Express
+```
+
+---
+
+## 三、容器侧:`MEDIA:` 标记未全部生成 `m.file` 事件
+
+### 严重度与状态
+
+| 项 | 内容 |
+|---|---|
+| 严重度 | 🟡 中(用户看不到全部文件卡片) |
+| 责任方 | **容器 / Matrix 适配器** |
+| 状态 | ❌ 未修复(App 已加对账提示兜底) |
+
+### 现象
+
+一个回合里,正文列出了 3 个文件链接,但 App 只渲染出 2 张卡片。
+
+### 容器原话(2026-11-16 直接询问 `agent-node-lj-test` 所得)
+
+> **(a)** 我用的是 `MEDIA:` 标记。在正文里写 `MEDIA:/绝对路径`,由 Matrix 适配器解析后
+> 以 `m.file` 附件事件发出,同时正文保留文本。
+>
+> **(b)** 不区分。单个和多个都是同一套:正文里出现几处就逐个解析并作为独立附件事件发出。
+>
+> **(c)** 那是我在一次多文件交付里,正文里的 `MEDIA:` 行没能让每个文件都落地成附件事件,
+> 实际只到了部分文件 —— 我当时的说法是「两条 MEDIA 没送达」。
+> 原因是**标记存在但适配器没有为它们生成对应的事件**(不是文件不存在、也不是路径写错)。
+
+### 交叉验证
+
+独立的两条排查线得出一致结论:
+
+- `docs/00-tracking/2026-11-17-容器文件返回问题诊断.md`:
+  附件投递**本身失败**(容器原文 `⚠️ Couldn't deliver the file attachment (…)`)
+- 2026-11-16 直接询问容器:**适配器没生成事件**
+
+### 修改点
+
+1. **修复适配器**:确保正文里每个 `MEDIA:` 标记都产出对应的 `m.file` 事件,
+   失败时也要有明确的错误回执(而不是静默丢弃)
+2. **建议增强**:在消息内容里带一个**自描述文件清单**(容器自己也建议过):
+
+   ```json
+   {
+     "msgtype": "m.text",
+     "body": "……",
+     "fmode_files": ["a.html", "b.docx", "c.pdf"],
+     "fmode_file_count": 3
+   }
+   ```
+
+   App 可用它做**精确对账**(当前 App 只能从正文文本里推断)。
+
+### App 侧已做的兜底
+
+`assistant-turn.ts::countMissingFiles()`:
+
+- 统计正文里明确的文件声明(`MEDIA:` 标记 + 本项目云盘链接),按文件名去重
+- 与实际卡片数比较,差额在卡片下方提示:
+  > ⓘ 还有 N 个文件未收到(正文已列出,点击正文链接可直接打开)
+
+**只提示、不伪造卡片** —— 卡片必须以真实的 `m.file` 事件为准。
+
+### 验收标准
+
+让容器一次输出 3 个文件,App 应看到:
+- 3 张卡片
+- **没有**「还有 N 个文件未收到」提示
+
+---
+
+## 四、后台推送(用户裁决:暂不做,仅记录)
+
+### 决策
+
+**用户 2026-11-18 明确裁决:后台推送先记录,暂不实施。**
+
+### 现状
+
+JPush 代码已完整实现但默认关闭(`fmodeJpushEnabled=false`),
+当前 APK 内不含 JPush 类,权限清单干净。
+
+### 完整链路缺口(共 4 项)
+
+| # | 缺什么 | 谁提供 | 预估 |
+|---|---|---|---|
+| 1 | 极光 AppKey | 需注册极光应用 | 1 天 |
+| 2 | 厂商通道证书 | 华为/小米/OPPO/vivo 开发者后台 | **华为需企业认证,1-2 周** |
+| 3 | 别名签发后台 | 平台开发(用户登录 → 绑 userId↔设备) | 3-5 天 |
+| 4 | **服务端触发链路** | 平台开发(监听 Matrix → 调推送 API) | 5-10 天 |
+
+### 不做的影响
+
+| 场景 | 能否收到通知 |
+|---|---|
+| App 在前台 | ✅ |
+| 切走后几秒内 | ⚠️ 不稳定 |
+| 后台超过 1-2 分钟 | ❌ |
+| App 被杀 | ❌ |
+
+产品上应明确告知用户:**通知需 App 保持运行**。
+
+---
+
+## 汇总
+
+| # | 问题 | 责任方 | 优先级 | 状态 |
+|---|---|---|---|---|
+| 一 | 多值 CORS | 平台 | 🟡 中 | 待修复 |
+| 二 | `/api-platform/` 反代 | 平台 | 🟢 低 | 待配置 |
+| 三 | `MEDIA:` 漏生成事件 | 容器 | 🟡 中 | 待修复 |
+| 四 | 后台推送 | 产品+平台 | — | **暂不做** |

+ 122 - 2
src/app/components/preview/file-preview/file-preview.ts

@@ -22,6 +22,7 @@ import { isCloudUrl } from '../../../core/s3-link';
 import { downloadAs, needsBlobPreview, toBlobUrl } from '../../../core/attachment-fetch';
 import { copyLink, openInNewTab } from '../../../core/open-link';
 import { isNativeApp } from '../../../core/api/platform-proxy.service';
+import { FileShareService } from '../../../core/file-share.service';
 
 /**
  * 预览呈现形态。
@@ -117,6 +118,11 @@ export type PreviewPresentation = 'rail' | 'full' | 'modal';
             }
 
 <div class="fp-tools">
+              @if (fileShare.available) {
+                <button type="button" class="fp-icon" aria-label="分享文件" [disabled]="fileShare.busy()" (click)="shareFile()">
+                  <i class="fa-solid" [class.fa-share-nodes]="!fileShare.busy()" [class.fa-spinner]="fileShare.busy()" [class.fa-spin]="fileShare.busy()" aria-hidden="true"></i>
+                </button>
+              }
               <ui-tooltip [disabled]="touchUi" content="下载">
                 <button type="button" class="fp-icon" aria-label="下载" (click)="download()">
                   <i class="fa-solid fa-download" aria-hidden="true"></i>
@@ -334,7 +340,7 @@ export type PreviewPresentation = 'rail' | 'full' | 'modal';
                       @if (frameStalled()) {
                         <div class="fp-html-stall">
                           <i class="fa-solid fa-circle-exclamation" aria-hidden="true"></i>
-                          <p>页面加载超时,可能是 CDN 缓存了旧版本或缺少跨域头。</p>
+                          <p>文件加载失败。请检查网络连接后重试;若网络正常,可能是文件地址已失效。</p>
                           <div class="fp-actions">
                             <button type="button" class="fp-btn fp-btn--primary" (click)="retryFrame()">
                               重新加载
@@ -1010,6 +1016,7 @@ export class FilePreviewComponent {
    * 平板横屏会判成 desktop;而「有没有鼠标」这件事只有原生壳能确定。
    */
   protected readonly touchUi = isNativeApp();
+  protected readonly fileShare = inject(FileShareService);
 
   /** 请求关闭 */
   readonly closed = output<void>();
@@ -1295,6 +1302,10 @@ export class FilePreviewComponent {
     }
   }
 
+  async shareFile(): Promise<void> {
+    await this.fileShare.share({ url: this.url(), name: this.name(), mimeType: this.mimeType() });
+  }
+
   /**
    * 复制文件的在线链接到剪贴板。
    *
@@ -1490,15 +1501,124 @@ export class FilePreviewComponent {
 
   onFrameLoad(): void {
     this.clearFrameTimer();
+    /*
+     * 🔴 断网时浏览器会**正常触发 load 事件**(渲染它自己的错误页),
+     * 于是原来的 `frameStalled.set(false)` 把「加载失败」当成了成功,
+     * 用户看到的是 Chrome 原生错误页:「网页无法打开 / net::ERR_NAME_NOT_RESOLVED」,
+     * 与 App 的设计语言完全不符(2026-11-18 真机实测)。
+     *
+     * ## 为什么不能用 navigator.onLine
+     *
+     * 真机实测:开启飞行模式后 `navigator.onLine` **仍然返回 true**
+     * (`connection.effectiveType` 还是 `4g`)—— MIUI 下 Android 的
+     * NetworkInfo 没有及时更新,这个属性在本场景**完全不可信**。
+     *
+     * ## 现在怎么做
+     *
+     * ① 同源 iframe 能读到内容 → 直接检查是不是浏览器错误页
+     * ② 跨域读不到 → 用一次**真实远程探测**判断网络(HEAD 一个已知域名)
+     */
+    void this.verifyFrameLoaded();
+  }
+
+  /**
+   * iframe 加载完成后校验是不是真的加载成功了(2026-11-18)。
+   *
+   * 分两步:先看能否读到同源内容(能读就直接判断),
+   * 读不到(跨域)再做一次远程可达性探测 —— 这是唯一可靠的方式。
+   */
+  private async verifyFrameLoaded(): Promise<void> {
+    const el = this.htmlFrame()?.nativeElement;
+    let readable = false;
+    try {
+      const doc = el?.contentDocument;
+      if (doc?.body) {
+        readable = true;
+        const text = (doc.body.innerText ?? '').trim();
+        if (text === '' || /ERR_[A-Z_]+|网页无法打开|无法访问此网站/.test(text)) {
+          this.failFrame();
+          return;
+        }
+      }
+    } catch {
+      readable = false;
+    }
+    if (readable) {
+      this.frameStalled.set(false);
+      this.frameLoading.set(false);
+      return;
+    }
+    /*
+     * 🔴 跨域 iframe 读不到内容(2026-11-18 第三次修正)。
+     *
+     * ## 关键事实(真机实测)
+     *
+     * 断网时 iframe **仍然会触发 load 事件**(浏览器渲染自己的错误页),
+     * 所以「有 load 事件 = 加载成功」这个假设**不成立**。
+     * 而跨域又读不到 `contentDocument`,DOM 层面无从区分。
+     *
+     * ## 做法:直接探测**目标文件本身**
+     *
+     *   · 断网 → 抛异常 → 判失败
+     *   · 文件 404 / 不可达 → 判失败
+     *   · 正常 → 判成功
+     *
+     * 探目标地址而不是别的域名,语义最准确:既不会被无关服务的慢响应误伤,
+     * 也顺带覆盖了「文件已失效」这种真实场景。
+     */
+    const ok = await this.probeTarget();
+    if (!this.open()) return; // 探测期间预览已关闭
+    if (!ok) {
+      this.failFrame();
+      return;
+    }
     this.frameStalled.set(false);
     this.frameLoading.set(false);
   }
 
+  /**
+   * 探测预览目标文件是否可读(2026-11-18)。
+   *
+   * 用 `HEAD` 省流量;不支持 HEAD 的服务端会回 405,那也算「连得上」。
+   */
+  private async probeTarget(): Promise<boolean> {
+    const target = this.buildFrameSrc() || this.safeUrl() || this.url();
+    if (!target) return true; // 无目标地址不判失败,交给超时兜底
+    try {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 6000);
+      const res = await fetch(target, { method: 'HEAD', signal: ctrl.signal, cache: 'no-store' });
+      clearTimeout(timer);
+      return res.ok || res.status === 405;
+    } catch {
+      return false;
+    }
+  }
+
+  private failFrame(): void {
+    this.frameStalled.set(true);
+    this.frameLoading.set(false);
+  }
+
   retryFrame(): void {
     this.frameStalled.set(false);
     this.frameRetry++;
     const el = this.htmlFrame()?.nativeElement;
-    if (el) el.setAttribute('src', '');
+    /*
+     * 🔴 先清空 src 再**显式写回目标地址**(2026-11-18 真机实测修复)。
+     *
+     * 原来只做了 `el.setAttribute('src', '')` —— 清空后 Angular 的
+     * 属性绑定没有变化,不会重新写回,于是 iframe 落在了
+     * `https://localhost/`(App 首页),既没加载目标文件,
+     * 错误提示框又因为 stall 状态还在而继续显示,两者叠在一起。
+     *
+     * 改为:清空 → 强制回流 → 写回真实地址,确保这次是**重新发起请求**。
+     */
+    if (el) {
+      el.setAttribute('src', 'about:blank');
+      void el.offsetHeight; // 强制回流,让浏览器立即应用清空
+      el.setAttribute('src', this.buildFrameSrc() || this.safeUrl() || this.url());
+    }
     this.startFrameTimer();
   }