一个看似普通的下载故障，为什么总在错误的地址上打转

做 ArkWeb 容器时，下载故障最麻烦的地方往往不是“有没有回调”，而是日志里的地址究竟代表哪一层。用户点击的是页面上的一个按钮，页面可能用脚本生成链接，也可能经过跳转、内容分发、鉴权或临时签名；下载组件最终看到的请求地址，只是链路某一刻的状态。若排障记录只保存当前页面 URL 或最终请求 URL，团队很容易围绕错误对象反复验证：页面可以打开，却解释不了下载为什么失败；请求地址可以访问，却找不到最初由哪个资源触发。

HarmonyOS 6.1.1/API 24 在 WebDownloadItem 上提供 getOriginalUrl()，让下载回调可以直接读取“这个下载对象记录的原始地址”。它的价值不是多显示一个字符串，而是把排障入口从页面猜测转到下载任务本身。本文站在 Web 容器开发者的角度，只回答一个问题：异常下载发生时，怎样以同一个 WebDownloadItem 为事实边界，记录请求 URL、原始 URL 和必要上下文，并形成可以重复核对的故障证据。

本次验证使用 API 24 x86_64 模拟器 127.0.0.1:5555，系统基线为 OpenHarmony 6.1.1 对应镜像。工程完成构建、安装、启动，并连续触发两次真实下载回调。固定样本没有重定向，所以 getUrl() 与 getOriginalUrl() 两次都返回同一个 data:text/plain 地址。这证明 getter 在该环境和样本中真实进入回调并稳定返回，不证明所有网络下载都一定产生不同的两个地址，也不外推为真机结果。

先把“页面原始地址”和“下载原始地址”分开

SDK 中存在两个容易混淆的同名方法。WebviewController.getOriginalUrl() 面向当前 Web 页面，它回答控制器所关联页面的原始地址；WebDownloadItem.getOriginalUrl() 面向一次下载任务，它回答下载对象记录的原始地址。类作用域不同，证明任务也不同。前者不能因为名字相同，就被复制到下载日志里冒充后者。

这个区别在故障现场非常重要。一个页面可以同时触发多个下载，每个任务可以有自己的 URL、文件名、MIME 类型和状态。若把 controller 的页面地址写入每条下载记录，日志表面上字段完整，实际却把“一对多”的关系压成同一个值。排查人员看到的不是下载事实，而是页面背景信息。正确做法是在 onBeforeDownload 收到 WebDownloadItem 后，从这个对象一次性读取相关字段，再把页面地址作为独立上下文保存。

版本边界也要写清。当前 API 24 SDK 声明里，下载委托和常用下载字段早于 API 24，WebDownloadItem.getOriginalUrl() 与 getReferrerUrl() 则标记为 since 24；controller 上的同名页面方法标记为更早版本。由此能得出的结论是“API 24 下载对象增加了可读取字段”，不能写成“ArkWeb 从这个版本才支持下载”，更不能把两个对象的版本说明拼成一项能力。

用一份原子快照记录回调，而不是分散更新日志

下载回调通常发生在页面状态不断变化的过程中。如果先记录请求 URL，随后异步读取原始 URL，再从另一个组件补页面地址，最终几项数据可能属于不同时间点。更稳妥的设计是把下载对象视为一次取证快照：三个 getter 在同一个回调、同一个 item 上连续读取，随后立即决定是否接受或取消任务。

页面使用一个小状态对象承载结果，它没有混入 controller URL，也没有预填“应该返回”的地址：

interface DownloadTraceState {
  requestUrl: string;
  originalUrl: string;
  referrerUrl: string;
  callbackState: 'idle' | 'received' | 'failed';
  errorMessage: string;
}

这里的 callbackState 不表示下载文件已经完成。received 只表示 onBeforeDownload 已进入、字段读取完成且测试任务已按设计取消。把“回调收到”和“文件下载成功”拆开，可以避免 Demo 页面的一枚绿色状态被误读成完整下载验收。

读取字段之后先处理任务，再更新界面

FIGURE SLOT 04

Replace with screenshot checklist item 04 here.

本次页面的目标是观察字段，不需要保存测试文件。独立审阅发现，最初实现把 cancel() 放在状态赋值之后：如果某个 getter 或响应式状态更新抛错，控制流会直接进入异常分支，取消动作就可能被跳过。最终实现把读取、取消和展示分成三个阶段。

let requestUrl = '';
let originalUrl = '';
let referrerUrl = '';
let readError = '';

try {
  requestUrl = item.getUrl();
  originalUrl = item.getOriginalUrl();
  referrerUrl = item.getReferrerUrl();
} catch (error) {
  readError = this.formatError(error);
}

try {
  item.cancel();
} catch (error) {
  this.markCancelFailed(error);
  return;
}

这段顺序表达了一个明确约束：字段读取即使失败，也要尝试取消测试任务；取消成功后，页面才更新次数和结果。真实业务如果需要保存文件，应把这里替换为经过权限、路径和策略校验的下载处理，而不是机械照搬 cancel()。文章讨论的是可观测性链路，不是通用下载器实现。

错误文本也不能只依赖 JSON.stringify(error)。原生 Error 常被序列化成 {}，最后只留下“失败”而没有原因。页面现在优先保留 Error.message，再使用字符串回退。生产日志还应记录业务错误码、下载任务标识和阶段，但不得把带签名的完整 URL 无限制写入公共日志。

页面生命周期是第一道排障关

Getter 写对了，不代表页面一定能进入回调。本次实现先遇到一个与新 API 无关的运行问题：Web(...) 直接写在 SectionCard 的内联 BuilderParam lambda 中，编译产物没有形成有效 Web 节点，运行时在 onControllerAttached 上触发空对象异常，应用退回桌面。把 Web 声明移到独立 @Builder 方法后，节点才按 ArkUI 组件方式创建。

第二个问题发生在控制器刚绑定时。页面以 about:blank 作为初始地址，若立刻调用 loadData()，初始导航与数据导航会竞争，日志曾出现 ERR_ABORTED(-3)。最终实现保留一次性调度保护，在下载代理安装后稍后发起 loadData()。页面文案也只写“loadData 已发起”，不在方法同步返回时提前宣称渲染已经完成。

这两个问题说明，下载回调不触发时应先按层级排查：Web 节点是否有效、controller 是否关联、delegate 是否安装、内容是否完成加载、点击是否命中，最后才轮到 getter。本次 faultlogger 和 hilog 保存了每一层的失败证据，因此修复不是靠重复点击碰运气。

固定输入为什么选择离线 data: 下载

验证 getter 时，网络波动、DNS、服务器响应头和证书都会引入额外变量。本次页面通过 loadData() 加载固定 HTML，再由 <a download> 触发一个固定 data:text/plain 资源。点击后真实进入 WebDownloadItem 回调，但回调读取字段后立即取消，不向磁盘保存文件，也不依赖外网服务器成功。

这种设计适合验证“回调和字段是否可读”，却不能模拟重定向链。由于目标本身就是 data: URL，实测中 request 与 original 相同完全合理。若要验证两者在跳转下载中的差异，需要另建可控 HTTP 服务，固定 30x 响应、最终资源、请求头与缓存状态，再保存每一跳的服务器日志。不能因为 API 名叫 original，就先假定本地样本一定返回另一个地址。

两次真实回调给出了什么证据

最终构建显示 BUILD SUCCESSFUL in 7 s 654 ms，覆盖安装和启动分别返回成功标记。随后在同一个页面实例中点击 Web 内容里的下载按钮。第一轮页面进入 received，次数为 1，request 与 original 同时显示固定 data: 地址；第二轮再次点击，次数增加到 2，字段保持一致且错误边界为“暂无错误”。

第一张图证明的是“字段来自一次真实回调并进入页面状态”，不是文件下载完成。页面同时展示预期引用页，是为了让实验条件可见；它没有被写入 getter 结果。

第二张图把偶发触发与可重复行为分开。PID 27709 的 hilog 中出现两组不同 GUID，每一组都有 DownloadItemImpl::Start 和随后 DownloadItemImpl::Cancel。它证明两个下载对象都真实建立并被取消，而不是按钮直接把次数改成 2。

当 request 与 original 相同时，日志仍然有价值

很多团队只有看到两个 URL 不同，才认为 getOriginalUrl() 有用。实际上，相同也是一个可以缩小范围的事实。它说明在当前离线样本里，下载对象没有暴露出“当前请求地址与原始地址不同”的现象。排障人员可以把注意力移到 MIME 类型、权限、保存路径、响应状态或 Web 内核策略，而不是继续猜测跳转。

真正的问题是日志是否能回答“这两个值是分别读取后恰好相同，还是程序只复制了一次”。因此记录结构里要保留字段名和来源方法，不能为了去重只存一个 URL。观察系统可以在展示层标记“same as request”，底层仍保存两个字段。未来换成重定向样本时，数据模型无需重构。

一棵从回调入口开始的排障树

第一类故障是回调完全没有进入。先确认 Web 内容是否真实加载，下载属性是否被内核识别，delegate 是否在用户点击前安装。若页面直接退出，优先看 faultlogger，而不是猜 getter 不支持。

第二类故障是回调进入但 getter 抛错。此时记录 API 版本、系统版本、错误码和下载对象状态，仍按业务策略取消或处理任务。不能捕获异常后继续显示默认地址并标记 received。

第三类故障是 request 与 original 相同。这不自动构成异常，应核对样本是否真的有重定向。只有服务器和网络链明确存在跳转，二者仍与预期不符时，才继续检查缓存、service worker、脚本生成地址或平台语义。

第四类故障是 original 为空。要区分空字符串、未调用、异常和 UI 未刷新。本次页面曾出现状态更新但 URL 文本不刷新的问题，原因是 Builder 参数按值捕获了初始字符串。最终让 Text 直接读取 @State traceState 后，真实返回才可靠显示。界面空白不等于 getter 一定为空，数据流也要核对。

生产日志不能照搬 Demo 的完整地址

原始 URL 可能包含临时令牌、用户标识、查询参数和内部路径。把它纳入排障不等于可以原样长期保存。容器层至少要做三件事：对敏感查询参数执行白名单或哈希化处理；把日志保留期和访问权限限定到故障调查需要；将页面上下文、下载对象字段和用户操作分列存储。

推荐的事件可以包含时间、任务 ID、URL 的 scheme/host/path 摘要、original 与 request 是否相同、referrer 是否存在、回调阶段、错误码和处理决策。完整 URL 只在受控调试会话中短期采集，并在导出前再次脱敏。这样既保留追踪能力，也避免为了排障建立新的数据泄露面。

一条可用的下载事件应该怎样建模

只有三列 URL 仍不足以支持跨团队排障。容器层需要把“用户动作”“下载对象”“处理决策”关联起来。用户动作回答谁在什么页面触发了什么控件；下载对象保存三个 getter、建议文件名、MIME 类型和任务标识；处理决策说明应用是接受、取消还是因策略拒绝。三个部分使用同一个关联 ID，但生命周期相互独立。

时间也不应只有一列。至少区分页面加载完成时间、用户点击时间、onBeforeDownload 进入时间、字段读取完成时间和任务决策时间。若回调迟迟不来，可以判断停在点击与内核识别之间；若字段已经读取但文件没有出现，可以继续查看保存路径和下载状态，而不是重新调查页面入口。

对于 URL，推荐同时保存结构化摘要和比较结果。结构化摘要包含 scheme、host、端口、路径后缀和脱敏查询键；比较结果包含 requestEqualsOriginal、hasReferrer 和是否跨域。这样常规监控不需要持有完整地址，也能统计“重定向下载比例”“空来源比例”和“跨域任务比例”。只有命中异常规则时，才在授权调试模式中采集更详细内容。

用可控重定向样本验证“原始”的含义

本次离线样本只能证明 original getter 可读，不能说明经过跳转后它具体保留哪一跳。下一阶段实验应由一个本地或测试网 HTTP 服务提供三个端点：入口地址返回一次可预测的 302，第二个地址再跳转，最终端点返回带下载响应头的固定小文件。服务端为每一跳记录请求 ID、时间和 Referer，客户端使用同一 ID 记录 getter。

测试时固定 Web 内核版本、缓存状态、网络代理和下载触发方式。第一轮在清空缓存后执行，第二轮保持相同条件重复，第三轮只改变重定向链。若 request 与 original 出现差异，可以与服务器日志逐跳比对；若仍相同，也应记录平台在当前条件下的实际语义，而不是根据浏览器经验改写。

脚本生成的 blob: 地址、data: 地址、普通超链接和服务端附件响应应分组验证。它们的来源模型不同，混成一组会让“原始地址”的结论失去条件。尤其是 blob 下载，下载对象可能只看到临时对象地址，真正业务资源需要由页面自己的映射表补充，这属于应用上下文，不是 getter 自动恢复的能力。

怎样把现场记录变成可重放用例

排障闭环不应停在一份日志。确认故障后，把已脱敏的 URL 结构、页面触发方式、响应头类别、是否重定向和预期处理决策转成测试夹具。自动化不必真的访问生产资源，可以由本地服务复现相同状态码和头部，让容器重新走一次回调链。

重放用例至少断言四件事：delegate 在点击前已安装；一次用户动作只产生预期数量的回调；request 与 original 分别写入而非互相复制；无论字段读取成功还是失败，测试任务都按策略取消。对于允许落盘的业务用例，再增加文件名、目录、校验值和清理结果。这样新版本升级后可以直接比较行为，不必等用户再次遇到同类问题。

截图只能证明某一轮页面状态，无法替代重放。本文保留两轮界面与两组 GUID，是为了把可见结果和内核日志关联；真正的回归资产还应包含服务器夹具、操作脚本和断言。证据层级越清楚，发布说明越不会把“一次成功”写成“所有场景兼容”。

兼容策略应该放在调用前，而不是异常后猜测

since 24 意味着调用方必须确认目标运行环境。若应用仍支持更低 API，代码应通过版本分支或独立能力模块隔离新 getter，低版本使用明确的降级字段并标记来源。不要先调用、捕获失败，再把 request URL 填进 original；这种做法会让日志看似完整，却失去字段语义。

多版本产品可以定义统一事件结构，但为每个值增加 source：例如 downloadItemOriginal、downloadItemRequestFallback 或 unavailable。分析系统据此决定哪些数据可以比较。低版本缺失不是错误，伪装成同一质量的数据才会误导排障。

升级验证也要覆盖页面生命周期。本次真正导致应用退出的是 Builder 位置，而不是 getter。SDK 升级后除了类型检查，还要在目标设备上走入口、内容加载、点击、回调、决策和退出完整流程。只有接口声明、工程构建和页面运行三层都清楚，兼容结论才可复核。

三类团队如何共享同一份事实

Web 容器团队负责保证事件结构、生命周期和异常安全；业务团队负责提供下载场景、允许域名和用户动作含义；安全与运维团队负责脱敏、留存、告警和访问审计。三方共享同一个事件协议，但不需要共享所有原始数据。

当客服收到“点击后没有文件”时，可以先按关联 ID 查询：页面是否触发、回调是否进入、original 是否可读、决策是否取消、下载状态是否继续。若容器在回调中主动取消，问题属于策略或测试模式；若没有回调，问题回到 Web 内容和内核；若已完成但用户找不到文件，再查目录和媒体索引。每一步都有明确所有者，避免把所有问题都丢给页面开发。

这也是原始 URL 的更大价值：它不是独立的调试装饰，而是事件协议中的一个定位字段。只有与阶段、任务 ID 和决策组合，它才能缩短调查路径；单独把完整 URL 打到控制台，既难搜索，也可能暴露敏感信息。

接入真实项目时的最小验收

工程验收不要只看编译。第一步核对 SDK 声明和目标 API；第二步确认页面与下载对象的方法没有混用；第三步构建、安装、启动分别记录；第四步用固定样本至少触发两次；第五步把 getter、错误和任务决策关联到同一个 ID；第六步检查文件是否按预期保存或取消；最后再用重定向、空 URL、下载失败和重复点击扩展样本。

如果产品需要下载落盘，还要增加目录权限、重名策略、空间不足、恶意文件和中断恢复测试。本文 Demo 主动取消，所以它只验证来源字段的回调链，不验证文件写入、进度通知或完成回调。

小结

发布前还应做一次反向核对：删除页面上的“预期下载地址”和“预期引用页”后，回调结果是否仍能独立成立；清空状态后再次点击，次数、时间和字段是否重新形成同一份事件；关闭网络后，离线样本是否仍然复现。这样的反向检查能发现界面把固定文案误当结果、旧状态残留和外部依赖三类问题。本文最终证据通过了离线重复操作，但没有覆盖网络重定向和真实文件保存，所以结论始终限定在下载对象字段读取链。

WebDownloadItem.getOriginalUrl() 真正改变的是排障的事实边界。开发者不必再从当前页面地址推测下载来源，而可以在真实下载对象上同时读取 request、original 和其他上下文。前提是严格区分类作用域、在同一回调形成原子快照、让取消或保存决策具备异常安全，并把构建、启动、回调和文件结果分层记录。

本次 API 24 模拟器验证连续两次返回相同的 request 与 original，且两项下载都被取消。这个结果没有戏剧性的 URL 差异，却是一份可靠基线：方法真实可读、数据流真实刷新、重复触发稳定、边界没有被预期值覆盖。下一步若要证明重定向场景下的原始地址差异，应引入可控服务器样本重新验证，而不是把预期写成结论。

附录：HarmonyOS 6.1.1 新特性开发环境与真机验证准入

1. 版本硬基线

本批新特性统一以 HarmonyOS 6.1.1 API 24 为目标版本。项目 sourceproject/build-profile.json5 必须保持：

{
  "compatibleSdkVersion": "6.1.1(24)",
  "targetSdkVersion": "6.1.1(24)",
  "runtimeOS": "HarmonyOS"
}

开发者不得为了绕过构建错误，把项目静默改为 API 26 或其他版本。版本变化会同时改变 API 声明、兼容设备、文章结论和文章事实范围。

2. 编译环境准入

在 DevEco Studio 的 SDK Manager 中，必须选择与项目一致的 HarmonyOS 6.1.1(API 24) SDK。仅有 system-image 只能启动模拟器，不能证明 ArkTS 项目可以编译。至少应核对以下编译组件：

组件	作用	准入要求
hms/ets	ArkTS/ETS API 声明与编译	目录存在，元数据与 Hvigor 兼容
hms/native	Native 编译支持	目录存在，元数据与 Hvigor 兼容
hms/toolchains	编译、签名和设备工具链	目录存在，hdc 可执行
hms/previewer	预览与设计期支持	目录存在，版本与 SDK 对齐
openharmony/toolchains	设备安装、启动与调试	hdc.exe 可调用

硬性判定不是“SDK Manager 显示了 API 24”，而是构建已经越过 SDK 扫描并进入 CompileArkTS。本项目曾遇到组件 metaVersion: 3.1.0 与项目自带 Hvigor 扫描器不兼容，最终报 00303168 SDK component missing；此时不能进入特性 API 编码和文章结论阶段。

3. 推荐构建链路

当前已验证可用的是 DevEco Studio 内置 Hvigor 与 DevEco JBR，而不是项目自带的旧/不兼容 Hvigor 组合：

$env:DEVECO_SDK_HOME='D:\Program Files\Huawei\DevEco Studio\sdk'
$env:JAVA_HOME='D:\Program Files\Huawei\DevEco Studio\jbr'
$env:Path="$env:JAVA_HOME\bin;$env:Path"
& 'D:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin\hvigorw.bat' `
  --no-daemon --mode module -p module=entry@default -p product=default assembleHap --stacktrace

准入日志必须至少出现：

Finished :entry:default@CompileArkTS
Finished :entry:default@PackageHap
BUILD SUCCESSFUL

如果失败停在 SDK 扫描、依赖解析或 ArkTS 编译之前，结论只能写“环境未解锁”。不要根据 IDE 能打开项目、预览器能显示页面或旧 HAP 仍能安装，推导新特性 API 可用。

4. HAP 安装与启动环境

安装验证至少记录设备、包名、HAP 来源和结果。当前项目基线如下：

项目	要求/已验证值
包名	com.csdn.harmonyos.featuredemos
项目 API	compatibleSdkVersion=6.1.1(24)、targetSdkVersion=6.1.1(24)
设备 API	与项目兼容范围匹配，当前 API 24
releaseType	项目、SDK、设备保持一致，当前为 Release
设备形态	本批 Demo 以横向 Pad 为主要截图形态；手机需单独复核
HAP 来源	当前 SDK 重新构建的产物，不沿用旧 HAP

$hdc='D:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\toolchains\hdc.exe'
& $hdc install -r 'sourceproject\entry\build\default\outputs\default\entry-default-unsigned.hap'
& $hdc shell aa start -a EntryAbility -b com.csdn.harmonyos.featuredemos

install bundle successfully 只证明 HAP 与设备的安装条件匹配；start ability successfully 只证明应用可以启动。两者均不证明 Map、Camera、Notification 听觉、AI 字幕或通行证识别已经成功。

参考资料

• HarmonyOS 6.1.1 新特性说明：https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/os-new-feature-611
• ArkWeb WebDownloadItem API：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-webview-webdownloaditem