新增一个 getter，不等于每次下载都有来源页

Web 容器里的下载来源常被写成一句过度简单的话：“记录当前页面 URL 就够了。”这在单页、单按钮、无跳转的演示里似乎成立，进入真实业务后却很快失效。一个页面可以嵌套多个框架，可以由脚本生成对象地址，可以从聊天消息、广告、文档预览或第三方登录结果触发下载；浏览器内核还会受 URL scheme、重定向、referrer policy 和用户操作方式影响。当前页面只是背景，并不天然等于下载对象返回的 referrer。

HarmonyOS 6.1.1/API 24 为 WebDownloadItem 提供 getReferrerUrl()。Web 容器开发者真正需要解决的，不是怎样把这个方法抄进回调，而是怎样解释它的值、空值和证据等级，让风控、审计和业务归因都不被一条看似完整的 URL 误导。

本次 API 24 模拟器实验给出一个非常克制的结果：固定 HTML 通过 loadData() 设置了 https://evidence.local/arkweb/referrer.html 作为 base URL，用户真实点击其中的 data:text/plain 下载链接，连续两次进入 onBeforeDownload；getReferrerUrl() 两次都返回空字符串，回调状态为 received，没有异常。这个结果不能支持“引用页已非空传播”，但可以清楚证明 getter 已真实调用，以及“实验里存在预期页面”与“下载对象返回 referrer”是两件事。

在数据模型里，至少要区分四个概念。页面 URL 表示 WebView 当前展示或加载的地址；用户入口表示哪个业务界面、消息或按钮发起操作；下载请求 URL 表示任务当前请求的资源；下载 referrer 表示下载对象在当前场景下报告的引用来源。四者可能相同，也可能部分缺失。

如果容器把页面 URL 无条件填入 referrer 列，报表会获得更高的“完整率”，却失去事实可信度。安全团队可能把一个脚本生成下载误判为受信页面直出，运营团队可能把第三方跳转归因给当前落地页，研发人员也无法再判断空值究竟来自平台、协议还是应用回填。

因此页面在 UI 上把“预期引用页”和 getReferrerUrl() 结果分成两个区域。前者描述实验条件，后者只显示 getter 的真实返回。空字符串为了可见性渲染成“（空字符串）”，状态对象内部仍保存原始空值，没有用 base URL 替换。

固定 base URL 的作用只是控制条件

FIGURE SLOT 03

Replace with screenshot checklist item 03 here.

loadData() 可以给内存 HTML 设置 base URL 和 history URL。本次页面用固定值减少输入变化，使每轮点击都从同一个文档条件出发：

this.webController.loadData(
  this.pageHtml,
  'text/html',
  'UTF-8',
  'https://evidence.local/arkweb/referrer.html',
  'https://evidence.local/arkweb/history.html'
);

这段代码能证明“页面加载时提供了固定 base URL”，不能证明“内核必定把它写入下载 referrer”。尤其当下载目标使用 data: scheme 时，它与普通 HTTP 子资源不同，可能形成不透明来源或遵循不同的 referrer 处理。实验者必须允许结果为空，否则验证会退化成用预期覆盖事实。

同理，historyUrl 用于历史记录语义，也不应被当作 referrer 候选。字段名里都出现 URL，不代表它们能互相替代。事实表应为每个值记录对象、调用点和版本，而不是只保留一列“来源地址”。

回调里只做真实读取，空值也进入状态

FIGURE SLOT 04

Replace with screenshot checklist item 04 here.

三个 URL 在同一个 WebDownloadItem 上连续读取。页面不使用 controller getter，不读取固定常量回填结果，也不因为空字符串把状态改成 failed：

requestUrl = item.getUrl();
originalUrl = item.getOriginalUrl();
referrerUrl = item.getReferrerUrl();

item.cancel();
this.traceState = {
  requestUrl,
  originalUrl,
  referrerUrl,
  callbackState: 'received',
  errorMessage: '暂无错误'
};

这里需要分清“调用成功”和“业务值完整”。getter 正常返回空字符串，说明 API 调用完成，业务层没有获得非空来源。它不同于 getter 抛出异常，也不同于 UI 没刷新。监控中至少应使用三个状态：available 表示非空值，empty 表示正常返回空串，error 表示调用失败。把后两者都归为“无数据”，会丢失排障方向。

测试页面在读取后取消任务，不验证文件落盘。两组 hilog 都出现独立 GUID 的 Start 与 Cancel，说明按钮不是直接模拟状态。空 referrer 发生在真实下载对象回调中，而不是静态占位。

两轮空字符串排除了哪些误判

FIGURE SLOT 05

Replace with screenshot checklist item 05 here.

第一轮点击后，页面显示 received、次数 1，request 与 original 为固定 data URL，referrer 明确显示空字符串，错误边界为“暂无错误”。

这张图证明空值与成功回调可以同时存在。它没有证明平台“永远不提供 referrer”，只证明当前页面加载方式、下载 scheme、模拟器和 API 版本组合下的真实结果。

第二轮在同一页面实例再次点击，次数增加到 2，referrer 仍为空。

重复结果减少了偶发 UI 刷新或单次初始化的可能性。与此同时，它仍不能替代另一组 HTTP 下载样本。可靠结论必须同时包含“已经证明什么”和“还没有证明什么”：已证明 getter 可调用、空值可稳定返回、页面未回填；未证明普通网络下载、重定向、iframe 或不同 referrer policy 下的非空行为。

为什么空值可能出现

FIGURE SLOT 06

Replace with screenshot checklist item 06 here.

第一类原因是 scheme。data:、blob:、file: 与 https: 的来源模型不同，内核可能不为某些下载附带常规引用页。第二类原因是文档或响应策略，例如 referrer policy 要求不发送，或跨源条件下只保留部分信息。第三类原因是触发方式，脚本生成对象、用户直接输入、重定向后下载和普通链接点击并不等价。

第四类原因是页面层级。顶层页面、iframe、弹窗和新窗口可能拥有不同的发起上下文。第五类原因是隐私或平台策略，系统可能在特定场景主动减少来源暴露。第六类原因才是代码问题，例如 delegate 安装太晚、读取了错误对象、状态捕获了初始值或异常被吞掉。

这些原因不能凭一张截图区分。排障需要控制变量：固定页面与下载资源，只改变 scheme；固定 scheme，只改变 referrer policy；固定策略，只改变顶层或 iframe；每组至少重复两次，并用服务端日志核对实际请求头。没有这种实验设计，“空”只能作为现象，不能直接归因。

风控系统如何使用 referrer，而不把它当裁决

FIGURE SLOT 07

Replace with screenshot checklist item 07 here.

来源字段适合成为风险信号，不适合成为单独的准入条件。一个非空 referrer 只能说明下载对象报告了某个来源，不能证明页面可信、用户知情或文件安全。攻击者可能控制受信页面的内容，合法下载也可能因隐私策略返回空值。

更合理的决策把多项事实组合起来：当前顶层域名是否受信、下载目标域名是否在允许范围、是否由明确用户手势触发、MIME 与文件后缀是否一致、original 与 request 是否跨域、referrer 是否存在、任务是否命中高风险类型。referrer 为空时，系统可以提高审计等级、要求二次确认或限制自动打开，而不是直接阻断所有下载。

规则还要记录版本和场景。若 API 24 才能读取对象级字段，低版本应标记 unsupported，不能与 API 24 的 empty 合并。前者是能力缺失，后者是能力存在但当前值为空。统计系统只有保留这一区别，升级后的完整率变化才有意义。

审计链需要“观察值”和“推断值”两套字段

审计记录经常把事实与推断写在同一列。例如 source=https://a.example 可能来自 getter，也可能来自当前页面，也可能是业务路由参数。后续调查者无法判断证据等级。建议明确分为 observed 和 inferred：observed 只保存平台 getter、请求和系统回调直接给出的值；inferred 保存应用根据页面、用户旅程或业务 ID 推导的来源。

每个推断值还应带规则版本和输入摘要。假设应用在 getter 为空时，以顶层页面 host 作为候选来源，那么记录应写 inferredSourceHost、rule=topPageFallback-v1，而不是改写 referrerUrl。规则变化后，历史事件仍能按当时逻辑解释。

本次 Demo 的固定 base URL 就属于条件，不属于观察结果。页面把它标成“预期引用页”，正是为了防止审稿和开发人员看到一个醒目的 URL 后，下意识认为 getter 已返回该值。

业务归因为什么更需要谨慎

运营分析希望知道下载来自哪个页面、活动或入口，但 referrer 只能覆盖其中一部分。用户可能从同一页面的不同按钮触发，也可能通过路由参数进入同一 Web 内容；仅按 URL 聚合会丢失组件和活动信息。业务侧应生成自己的匿名交互 ID，把页面、按钮、活动和下载任务关联起来。

当 getter 返回非空值时，它可以校验业务归因是否与内核观察一致；为空时，业务 ID 仍能提供产品路径，但必须标记为应用侧归因。两套来源互相验证，而不是相互覆盖。若两者冲突，应进入异常队列，检查跳转、嵌套页面、脚本生成或埋点错配。

归因数据也涉及隐私。完整 referrer 可能带查询参数、用户标识和搜索词。分析系统通常只需要规范化 host、路径模板和活动 ID，不需要保存全部 URL。脱敏应在设备或受控日志入口完成，避免先上传敏感地址再在服务端清洗。

一套可执行的空值处理协议

回调进入后，第一步记录 API 与系统环境；第二步读取 request、original、referrer，并分别保留空值；第三步执行下载决策；第四步把 observed 数据写入受控事件；第五步由策略层生成推断和风险等级。任何一步失败都记录阶段，不用默认值掩盖。

当 referrer 非空时，先解析 scheme 和 host，执行脱敏与允许域校验，再参与决策。当返回空字符串时，记录 referrerState=empty，结合用户手势、页面上下文和目标类型决定是否提高确认等级。当调用抛错时，记录 referrerState=error 和错误码，并检查兼容环境。低版本则写 unsupported。

这个协议让 UI、日志和后台统计使用相同语义。客服看到“空值”不会误报成 SDK 异常，安全团队也不会把低版本缺失算作可疑下载。最重要的是，应用永远不改写 getter 原值，所有补充信息都有自己的字段。

怎样补齐非空传播验证

下一组验证应使用可控 HTTPS 测试服务，而不是公共网站。服务提供固定引用页和下载端点，记录请求头与任务 ID；页面分别设置默认、no-referrer、origin 等策略，再从顶层和 iframe 触发。客户端同时记录 getter，服务器记录实际 Referer，两个方向交叉核对。

每组实验都固定系统镜像、Web 内核、缓存、网络和手势，并至少重复两次。若 getter 返回完整 URL、origin 或空值，都按条件记录。只有这样，文章才能进一步讨论“哪类场景返回什么”；本次离线 data 实验不能替代它。

真机验证也有必要，但不能为了得到非空值临时更换不受控页面。真机与模拟器应使用同一测试服务、同一脚本和同一字段表，差异才有解释价值。否则一端返回非空、另一端为空，也无法判断来自设备、页面还是服务端配置。

企业文档下载场景怎样落地

企业门户常在 Web 页面中提供合同、报表和培训资料下载。安全要求通常不是“所有来源页都必须非空”，而是“只有明确用户动作、受信业务入口和允许文件类型的组合才能自动进入保存流程”。容器可以在点击时生成一次匿名 action ID，回调里把它与下载对象关联，再读取 referrer。

若 referrer 非空且 host 属于门户域名，系统仍要继续检查目标域名、文件类型和用户权限，因为受信页面也可能被注入异常链接。若 referrer 为空，但 action ID 能证明用户刚刚点击了授权页面的下载按钮，策略可以允许下载并提高审计等级，而不必一刀切阻断。若既无 referrer，也没有近期用户动作，则更适合要求二次确认。

文档名称和 URL 往往包含客户、项目或员工信息。日志中应保存文件类型、大小区间、目标域摘要和权限结果，完整路径只在受控调查中查看。这样 getReferrerUrl() 参与了安全判断，却没有成为新的敏感信息收集口。

跨域登录后的下载为什么更复杂

另一个常见流程是先跳到统一身份认证，再回到业务页生成临时下载地址。用户眼中的来源是业务系统，下载请求却可能指向对象存储或 CDN。页面顶层 URL、登录跳转 URL、业务回调页和下载 referrer 可能各不相同。

如果审计只接受“referrer 与下载目标同域”，合法的对象存储下载会被误判；如果只要当前页面受信就全部允许，又会放大开放重定向和脚本注入风险。合理模型应记录域关系：业务页面域、身份域、下载目标域是否出现在批准拓扑中，original 与 request 是否跨域，referrer 是否与某一合法节点一致。

当 getter 为空时，不能自动选择跳转链中的任一地址回填。应用可以用已签名的业务 transaction ID 证明下载属于哪次授权流程，并把它记录为应用证据。平台观察值仍为空，两种证据共同支撑决策。这个分层能避免后续把业务签名误说成 ArkWeb getter 的返回。

为来源数据建立质量指标

上线后只统计“有多少非空 URL”意义有限。更有效的指标包括：按 API 版本和 scheme 划分的 non-empty、empty、error、unsupported 比例；request 与 original 相同比例；有明确用户手势但 referrer 为空的比例；业务归因与内核观察冲突比例；因来源不足触发二次确认的比例。

这些指标必须按场景分桶。data 或 blob 下载的空值比例不能与 HTTPS 附件混在一起，顶层页面也不能与 iframe 混合。否则产品升级后某类下载占比变化，就会被误读成平台字段质量退化。看板还要标记规则版本和系统版本，使趋势具有可比较条件。

报警也不应针对单个空值，而应关注异常变化。例如同一 HTTPS 业务在升级后 empty 比例从少量突然升高，才值得检查 referrer policy、内核版本或接入代码。对于一直为空的受控 data 测试，它是健康基线，不是告警。

一次“空值事故”应该怎样复盘

假设版本发布后，安全平台报告某批下载没有来源。复盘第一步不是补默认值，而是抽取匿名任务 ID，核对系统版本、URL scheme、页面层级和触发方式。第二步查看回调是否 received，getter 是空字符串还是抛错，UI 是否真实刷新。第三步再检查页面策略、跨域跳转和服务端 Referer。

如果发现应用曾在空值时写入当前页面地址，必须把历史数据标记为 inferred，不能继续与 observed 混用。如果发现 delegate 安装晚于点击，应修复生命周期并重新验证。如果 data 下载稳定为空，则把它写入场景基线，不要求平台返回并不存在的来源。

复盘结论要形成可重放用例和规则变更，而不是只写“加强监控”。至少补一个对应 scheme 的固定页面、两次触发、getter 状态断言和服务端交叉证据。下一次 SDK 或 Web 内核升级时，这些用例可以在发布前发现行为变化。

产品交互也要反映证据等级

最终用户不需要看到 getReferrerUrl() 术语，但产品可以根据来源证据调整交互。低风险且证据完整的下载直接进入标准确认；来源为空但用户动作明确的下载展示目标域名和文件类型；来源、手势和业务授权都不足时，再使用更强提示或阻断。

提示文案应说明可验证事实，例如“该文件来自外部域名”或“无法确认页面来源”，不要写“文件不安全”。空来源是信息不足，不是恶意判定。用户做出选择后，审计记录保存决策与当时证据等级，便于后续调查。

这种设计把 API 字段转化为渐进式风险交互，而不是后台静默打分。它也给产品团队清晰边界：getter 提供信号，策略组合信号，界面表达不确定性，任何一层都不单独承担最终真伪判断。

发布和评审时应拒绝的表述

第一种错误是“设置 base URL 后，getReferrerUrl() 就会返回这个地址”。本次实测直接说明不能这样推导。第二种错误是“返回空字符串说明 API 无效”。getter 已真实进入并正常返回，空值是数据结果。第三种错误是“有 referrer 就能证明下载安全”。它最多是风险信号。

第四种错误是用 controller 当前页替代下载对象字段。第五种错误是把编译成功写成字段返回。第六种错误是只展示最终 URL，不展示触发动作、回调状态和环境。任何一种都会让证据看起来完整，实际无法复现。

评审者可以做一个简单检查：遮住页面上的预期值，只看 getter 区域和日志，结论是否仍成立；把空值换成非空预期，文章是否有真实证据支持。如果答案是否定的，就必须降级措辞或补实验。

小结

在代码评审中还可以加入一条强制断言：任何写入 referrerUrl 的位置都必须直接持有当前 WebDownloadItem，页面 URL、路由参数和预期常量只能写入其他字段。测试则分别构造非空、空字符串和异常三种结果，确认界面状态、策略输入和审计事件不会合并。这样即使后续团队增加兜底归因，也不会悄悄改变平台观察值的含义。

上线审批表还应单列“非空来源是否已经在目标场景验证”。若答案是否定的，允许发布的只能是空值处理、兼容接入和后续验证方案，标题与摘要都不能使用“成功获得引用页”一类完成态措辞。这条门禁能阻止发布压力把预期结果提前写成事实。

WebDownloadItem.getReferrerUrl() 的意义，是让下载对象多一个可观察来源，而不是承诺每次下载都返回非空页面地址。Web 容器要把它作为 observed 字段，明确区分非空、空字符串、错误和不支持，再与页面上下文、用户手势和业务 ID 组合。

本次 API 24 模拟器在固定 loadData 页面和 data 下载下连续两次返回空字符串。我们没有用预期 base URL 填补它，也没有把空值写成失败。正是这种克制，才让证据能进入审计与决策：团队知道 getter 已运行，知道当前样本没有非空来源，也知道下一步应换用可控 HTTP 链验证，而不是继续围绕一个被人工补齐的 URL 做错误归因。

必要条件｜运行前检查清单

检查项	当前工程要求	运行前动作
SDK/API与构建工具	HarmonyOS 6.1.1、API 24、ArkTS、ArkUI、Hvigor	用 DevEco Studio 同步 API 24，执行 assembleHap
Kit引入	按本文技术点引入对应 @kit.* 或系统模块	检查 import 与 API 24 类型声明一致
模块/页面配置	entry 为 Stage 模型，页面登记在 main_pages.json	核对页面路由和 module.json5
设备权限/动态授权	Camera、AI字幕使用 CAMERA/MICROPHONE；网络使用 INTERNET	首次运行时完成授权，拒绝时不得继续调用能力 API
系统能力/硬件	按技术点检查摄像头、麦克风、地图、视觉模块或文件能力	在目标设备确认能力存在，再执行核心操作

运行前固定准备三张图片，并在对应检查项说明后插入。01必须能看清 DevEco Studio 的 API 24/构建配置；02必须能看清模拟器或真机权限状态；03必须能看清系统版本、API 级别和设备能力。

设备权限检查完成后插入：

MapKit文章增加服务配置检查：在 AppGallery Connect 创建/选择项目，绑定与工程一致的包名和签名，开通 MapKit 并按控制台要求完成应用服务凭据/授权配置后再运行地图能力。截图只能保留包名、服务开关和脱敏项目标识，不能展示密钥或私钥。