前陣子接到一個(gè)需求鴻蒙版應(yīng)用里聊天窗口和內(nèi)容信息流都要支持粘貼鏈接后自動生成富媒體摘要卡片。Flutter 側(cè)主工程之前用了 simple_link_preview 這個(gè)三方庫在 Android 和 iOS 上跑得很順換到鴻蒙后卻直接報(bào) MissingPluginException。原因不復(fù)雜——simple_link_preview 的原始工程只提供 Android 與 iOS 的原生實(shí)現(xiàn)并沒有注冊鴻蒙側(cè)的平臺通道。所以擺在我面前的路就很明確要么在業(yè)務(wù)層另寫一套抓取邏輯要么把這個(gè)庫的鴻蒙化適配補(bǔ)上。最終我選了后者。這篇文章就是這次適配的完整復(fù)盤從抓取原理到鴻蒙側(cè)實(shí)現(xiàn)再到各種兼容性坑盡量把可以直接抄作業(yè)的細(xì)節(jié)都寫出來。1. 為什么社交應(yīng)用需要鏈接預(yù)覽以及為什么值得做鴻蒙化1.1 鏈接預(yù)覽給體驗(yàn)帶來的改變用戶貼出鏈接時(shí)如果只是顯示一長串 URL閱讀成本很高。有了卡片預(yù)覽用戶能看到標(biāo)題、描述和主圖點(diǎn)擊的意愿也明顯更高。在聊天場景里這還能起到“預(yù)確認(rèn)”作用避免用戶誤點(diǎn)不明鏈接。在內(nèi)容社區(qū)里側(cè)邊欄分享、文章聚合都依賴這種卡片。可以說鏈接預(yù)覽已經(jīng)從“加分項(xiàng)”變成社交與內(nèi)容應(yīng)用的底線體驗(yàn)。我做過一個(gè)小改動后對比信息流內(nèi)鏈接點(diǎn)擊率翻了不止一倍。這也解釋了為什么我們會在一開始就引入 simple_link_preview它把抓取、解析、展示三件事封裝成一套 Flutter 組件業(yè)務(wù)側(cè)只需要丟一個(gè) url 進(jìn)去。對多端團(tuán)隊(duì)來說這種可復(fù)用性非常值錢。原來在 Android 和 iOS 上只要在 pubspec 里加依賴、調(diào)用 LinkPreview 組件就能在聊天列表、帖子詳情、私信會話里展示標(biāo)準(zhǔn)鏈接卡片。團(tuán)隊(duì)內(nèi)部不需要關(guān)心 OpenGraph 協(xié)議細(xì)節(jié)也不需要維護(hù)一堆正則表達(dá)式。鏈接預(yù)覽的另一層價(jià)值是“信息可信度透出”。用戶在點(diǎn)擊外鏈之前可以從卡片上看到來源域名可以有效防范釣魚鏈接。因此我們在做鴻蒙適配時(shí)不只是把抓取功能搬過來還要保證域名、圖標(biāo)、標(biāo)題這些信任元素完整渲染出來。一旦有一個(gè)頁面抓不到標(biāo)題整張卡片就會變成一堆無意義的網(wǎng)址用戶心里下意識會覺得產(chǎn)品不夠?qū)I(yè)。1.2 鴻蒙化適配的真正難點(diǎn)很多人以為適配無非是改網(wǎng)絡(luò)庫其實(shí)真正的難點(diǎn)是 Flutter 插件在鴻蒙上的生命周期和平臺通道注冊方式不同。Android 的插件類繼承FlutterPlugin并實(shí)現(xiàn)MethodCallHandler鴻蒙的 ArkTS 插件則要處理 Flutter 引擎?zhèn)魅氲腂inaryMessenger再注冊MethodChannel。這兩個(gè)平臺通道協(xié)議并不自動互通必須手動補(bǔ)上。simple_link_preview 的 Dart 層調(diào)用的是它自己內(nèi)部的某個(gè) channel 名鴻蒙側(cè)如果不知道這個(gè) channel 名就無法攔截請求如果知道就可以用同名 channel 接管。所以最省事的路徑是fork 一份 simple_link_preview保留原有 Dart API在原生目錄里補(bǔ)一個(gè) ohos 實(shí)現(xiàn)。這里有一個(gè)選擇自己新建一個(gè)插件用與 simple_link_preview 相同的 MethodChannel 名稱也可實(shí)現(xiàn)“偽適配”。但這種做法要保證兩邊數(shù)據(jù)格式完全一致反而容易在版本迭代后出現(xiàn)字段缺失。我更推薦 fork 后在原生目錄做適配理由很簡單Dart 層不會漂移插件升級時(shí)你只需要并一下原生實(shí)現(xiàn)。鴻蒙側(cè)插件注冊的入口與 Android 差異很大但只要理解了 BinaryMessenger 這個(gè)核心對象剩下的就是按模板填補(bǔ)代碼。2. simple_link_preview 的抓取與渲染鏈路到底做了什么2.1 OpenGraph 與元信息回退規(guī)則這里先明確一個(gè)概念鏈接預(yù)覽不是“爬蟲”它只讀取網(wǎng)頁 head 里的元數(shù)據(jù)。主流社交裂變都基于 OpenGraph 協(xié)議頁面作者會顯式聲明og:title、og:description、og:image。協(xié)議本身很簡單就是一組 meta 標(biāo)簽。真正麻煩的是抓到不符合協(xié)議的老網(wǎng)頁以及各網(wǎng)站字段缺失千奇百怪的情況。所以抓取模塊需要具備回退規(guī)則沒有og:title時(shí)用title標(biāo)簽沒有og:description時(shí)用meta namedescription沒有og:image時(shí)則找一個(gè)頁面里最接近正文的圖片或者退回 favicon。如果連標(biāo)題都沒有那就只能用 URL 本身作為展示文案。這個(gè)回退鏈條需要在鴻蒙側(cè)完整實(shí)現(xiàn)否則卡片很容易出現(xiàn)空白標(biāo)題。舉一個(gè)實(shí)際例子有些論壇頁面標(biāo)題寫在h1里meta description 完全為空og 標(biāo)簽也沒有。此時(shí)最穩(wěn)妥的做法是依次嘗試 og 協(xié)議、普通 meta、title、h1最后兜底返回空字符串。每一層回退都要在代碼里單獨(dú)處理不能把整段邏輯塞進(jìn)一個(gè)正則里。另外圖片字段可能是站內(nèi)相對路徑也可能是協(xié)議相對地址比如//cdn.example.com/cover.png這些都要在原生側(cè)轉(zhuǎn)換成完整可訪問的 URL。2.2 數(shù)據(jù)格式怎么定才不會讓上層 UI 重寫在正規(guī)插件里抓到的數(shù)據(jù)會被抽象成 MetaData 或類似對象。包含至少 7 個(gè)字段url、canonicalUrl、title、description、imageUrl、siteName、videoUrl如果是視頻頁。鴻蒙側(cè)的原生解析結(jié)果應(yīng)該以 JSON 對象返回給 Dart。JSON 的 key 不要隨便起名必須跟原庫 Dart 類字段一致。我們可以把抓取結(jié)果用 Map 返回例如{url: ..., title: ..., imageUrl: ...}。這里有個(gè)經(jīng)驗(yàn)許多適配者直接把 HTML 全部返回給 Dart 層解析雖然可以實(shí)現(xiàn)但性能非常差而且會把原庫的 MethodChannel 協(xié)議改掉。正確做法一定是原生側(cè)完成網(wǎng)絡(luò)請求和初步解析Dart 側(cè)只接收結(jié)構(gòu)化字段。如果是在自己 fork 的工程里做適配可以先看一下原庫 Dart 端的fromJson方法把 JSON 結(jié)構(gòu)一比一對齊這樣上層組件不用改圖片懶加載、緩存策略也不會受影響。3. 鴻蒙化適配的完整落地步驟3.1 插件工程與同名 Channel 注冊我建議的工程結(jié)構(gòu)是把 simple_link_preview 項(xiàng)目克隆到本地作為內(nèi)部維護(hù)分支在 pubspec.yaml 里保留原來的包名同時(shí)增加 ohos 平臺的插件聲明在原生目錄下新建ohos模塊代碼放在entry/src/main/ets/plugins/。如果是新插件橋接步驟如下用flutter create --templateplugin初始化插件然后修改 pubspec.yaml在 plugin 聲明里加入 ohos 平臺。App 側(cè)要引入這個(gè)插件。在 ArkTS 里插件入口需要拿到 Flutter 引擎的 messenger。這里給出最核心的注冊邏輯簡化let messenger: Object context.resourceManager.getContext(); const channel new MethodChannel(messenger, simple_link_preview); channel.setMethodCallHandler((call) { if (call.method fetchMetadata) { return this.fetchMetadata(call.arguments.url); } });老實(shí)說 ArkTS 的具體入口在不同 Flutter 鴻蒙版本中寫法略有差異但核心思路一致拿到 BinaryMessenger 后注冊與 Dart 側(cè)相同的 channel 名再處理方法調(diào)用。無論原 library 內(nèi)部用的是什么 channel你只要在鴻蒙側(cè)聲明相同的字符串就能接管。需要注意的是有些版本的 Flutter 插件是異步初始化channel 注冊時(shí)機(jī)一定要在 Flutter 視圖加載完成之后否則會接收不到 Dart 側(cè)發(fā)來的第一條消息。我在第一次驗(yàn)證時(shí)就遇到“Dart 側(cè)調(diào)用報(bào)沒實(shí)現(xiàn)但代碼明明注冊了”的情況最后發(fā)現(xiàn)是插件入口類沒有被加載需要在鴻蒙的模塊配置文件里顯式聲明插件entry。3.2 鴻蒙側(cè)實(shí)現(xiàn)網(wǎng)絡(luò)請求與 HTML 解析網(wǎng)絡(luò)請求基于系統(tǒng)能力實(shí)現(xiàn)。偽代碼import { http } from kit.NetworkKit; async function fetchUrl(url: string): Promisestring { const httpRequest http.createHttp(); const response await httpRequest.request(url, { method: http.RequestMethod.GET, connectTimeout: 8000, readTimeout: 12000, followRedirects: true, header: [{ User-Agent: UA_BROWSER }] }); if (response.responseCode ! 200) { return ; } return response.result.toString(); }這里有幾個(gè)關(guān)鍵點(diǎn)第一一定要設(shè)置瀏覽器 UA。我實(shí)測過不少內(nèi)容站點(diǎn)會直接拒絕帶 Flutter 默認(rèn) UA 的請求返回 403。第二followRedirects必須開否則短鏈和帶有跳轉(zhuǎn)的鏈接都抓不到。第三超時(shí)不能設(shè)太長卡片等待時(shí)間超過 6 秒用戶就會覺得卡死。我固定用 8 秒連接、10 秒讀取。第四response.result.toString()并不總是按照 UTF-8 解碼頁面如果聲明的是gb2312或gbk這里就會直接亂碼后面解析再多也白搭。HTML 解析不建議一上來就寫巨型正則而是先做簡單的規(guī)范處理把正則設(shè)為忽略大小寫只匹配標(biāo)簽和屬性不要對內(nèi)容做大小寫轉(zhuǎn)換。如下function parseMeta(html: string, key: string): string { let regex new RegExp(meta[^](?:property|name) key [^]content([^]*), i); let m html.match(regex); if (m) return m[1]; regex new RegExp(meta[^]content([^]*)[^](?:property|name) key , i); m html.match(regex); if (m) return m[1]; return ; }正則看起來思路清晰但有個(gè)現(xiàn)實(shí)問題meta 標(biāo)簽的 content 屬性值可能包含轉(zhuǎn)義字符比如amp;、quot;。如果直接把值塞給標(biāo)題組件UI 上會顯示amp;而不是。所以拿到原始值后還要做 HTML 實(shí)體解碼比如替換amp;、lt;、gt;、quot;、#39;。更穩(wěn)的做法是遍歷所有meta標(biāo)簽用字符串截取的方式分別讀取屬性名和 content 值。雖然這樣性能略低但頁面通常只有幾十個(gè) meta完全可接受。3.3 卡片渲染與數(shù)據(jù)裝配拿到元數(shù)據(jù)后回到 Flutter 側(cè)我會用最近流行的卡片結(jié)構(gòu)上面是圖片下面是標(biāo)題兩行、描述一行、來源域名一行。代碼可以寫一個(gè) LinkCard 組件class LinkCard extends StatelessWidget { const LinkCard({super.key, required this.meta, this.onTap}); final LinkMetaData meta; final VoidCallback? onTap; override Widget build(BuildContext context) { return Card( margin: EdgeInsets.zero, clipBehavior: Clip.antiAlias, child: InkWell( onTap: onTap ?? () openUrl(meta.url), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ _buildImage(), Padding( padding: const EdgeInsets.all(12), child: Column( crossAxisAlignment: CrossAxisAlignment.start, children: [ Text(meta.title, maxLines: 2, overflow: TextOverflow.ellipsis), if (meta.description ! null) Text(meta.description, maxLines: 2, overflow: TextOverflow.ellipsis), SizedBox(height: 8), Row( children: [ Icon(Icons.link, size: 14), SizedBox(width: 4), Expanded(child: Text(meta.siteName ?? parseDomain(meta.url))), ], ), ], ), ), ], ), ), ); } }關(guān)于圖片我建議外層用AspectRatio固定比例不要直接給固定高度。原因很簡單每張圖原始尺寸不同直接固定高度要么裁太多要么留白。如果不確定圖片尺寸可以設(shè)置AspectRatio(aspectRatio: 1.91)也就是 16:9 的變形版。加載時(shí)用loadingBuilder做骨架或者灰塊避免圖片加載后卡片高度跳動。加載失敗則把圖片區(qū)域換成一個(gè)小圖標(biāo)或者直接折疊不能讓白色裂圖影響用戶體驗(yàn)。還有一點(diǎn)很多人忽略卡片里的圖片到底由誰下載我的建議是鴻蒙原生側(cè)只負(fù)責(zé)返回圖片 URL不要順手把圖片下載成 base64 再回傳。這樣做會讓 MethodChannel 的數(shù)據(jù)包變得非常大而且 Dart 側(cè)無法復(fù)用ImageCache。Flutter 自帶的Image.network會走 Flutter 引擎的圖片緩存再次展示時(shí)成本很低所以把 URL 傳出來就夠了。4. 適配過程中的坑與排查實(shí)錄4.1 網(wǎng)絡(luò)權(quán)限和明文流量限制鴻蒙應(yīng)用默認(rèn)不允許明文 HTTP 流量類似 Android 9 之后的網(wǎng)絡(luò)安全配置。所以如果你測試的鏈接里有 http:// 老站卡片會一直失敗。在接入方的 module.json5 里要加權(quán)限并配置網(wǎng)絡(luò)安全{ module: { requestPermissions: [ { name: ohos.permission.INTERNET } ] } }如果要兼容 HTTP 明文還需要在應(yīng)用配置文件里打開網(wǎng)絡(luò)安全相關(guān)項(xiàng)具體名字因系統(tǒng)版本而異。但我不建議全局放開最好把需要允許明文訪問的域名加到白名單里。實(shí)際測試時(shí)我遇到的情況是插件本身報(bào)沒有網(wǎng)絡(luò)權(quán)限一開始還以為是解析問題后來才發(fā)現(xiàn)是 entry 模塊沒加權(quán)限。這個(gè)坑屬于接入方配置很容易漏。另外鴻蒙上的網(wǎng)絡(luò)請求不能忽略“沙箱”差異。部分系統(tǒng)版本里直接在 UIAbility 上下文發(fā)起 socket 請求會受隱私策略限制需要把請求放在合適的上下文環(huán)境中。如果后續(xù)出現(xiàn)“模擬器能抓真機(jī)抓不了”的問題優(yōu)先檢查系統(tǒng)網(wǎng)絡(luò)策略和權(quán)限窗口。4.2 不同站點(diǎn)解析差異實(shí)測我做了幾組典型頁面測試發(fā)現(xiàn)常見的異常情況有這幾類場景表現(xiàn)處理方案meta 屬性順序不一樣正則匹配不到同時(shí)匹配兩種順序或遍歷標(biāo)簽og:image 是相對地址圖片加載 404用 new URL(relative, pageUrl) 拼全頁面是 gb2312 編碼中文全亂碼檢測 charset做轉(zhuǎn)碼或返回失敗有多次跳轉(zhuǎn)短鏈抓不到followRedirects 打開網(wǎng)站開啟了反爬返回 403模擬瀏覽器 UA必要時(shí)加 Referer其中相對地址這個(gè)問題最容易疏忽。很多頁面作者寫og:image時(shí)直接用/img/cover.jpg并不帶域名。如果直接把這一串塞給Image.network一定會 404。解決辦法是在原生側(cè)把相對路徑拼成絕對 URL即拿目標(biāo)頁面的協(xié)議和域名拼一下。另外還要注意 CMS 生成的縮略圖字段可能完全沒有 scheme比如//cdn.example.com/xxx.jpg需要手動補(bǔ)https:。還有個(gè)容易被漏掉的點(diǎn)是og:image可能對應(yīng)一個(gè)視頻封面接口接口返回的是一段重定向地址比如從/redirect?urlxxx再跳到真實(shí)圖片。如果鴻蒙側(cè)只是簡單地把第一個(gè) og:image 字符串返回Flutter 端加載時(shí)可能超時(shí)。所以我建議在原生側(cè)對圖片 URL 也做一次輕量 HEAD 請求校驗(yàn)失敗就回退到其他圖片候選。但這個(gè)操作會增加一次網(wǎng)絡(luò)請求實(shí)際中要權(quán)衡或者在 Dart 層用errorBuilder兜底即可。4.3 圖片與緩存策略卡片重復(fù)出現(xiàn)同一鏈接時(shí)如果每次都重新發(fā)請求不僅慢還可能被目標(biāo)站點(diǎn)限流。我建議在 Flutter 側(cè)加一個(gè)簡單的內(nèi)存 LRU 緩存以 URL 為 key緩存時(shí)間設(shè)為 5 分鐘。如果是聊天記錄再次展示也許要持久化到數(shù)據(jù)庫因?yàn)橥绘溄涌赡軙环春芏啻?。這時(shí)不能在 Dart 層直接序列化大圖片只緩存元數(shù)據(jù)圖片本身交給系統(tǒng)內(nèi)存圖片緩存處理。圖片如果加載不出來原因通常不是網(wǎng)絡(luò)而是圖片 URL 帶簽名參數(shù)第一次請求有效第二次過期。解決辦法原生抓取時(shí)不下載圖片只把最終經(jīng)過重定向后的圖片 URL 返回給 Flutter這樣 Flutter 端拿到的是穩(wěn)定地址。如果做不到至少用errorBuilder兜底把標(biāo)題撐滿卡片而不是顯示破圖。這里的兜底邏輯要區(qū)分“圖片還沒加載”和“圖片加載失敗”兩種情況用一個(gè)狀態(tài)字段標(biāo)記會更明確。另外卡片緩存要注意“鍵”的選擇。同一個(gè)鏈接可能因?yàn)閡tm參數(shù)不同產(chǎn)生多個(gè)緩存條目比如example.com/page?id1fromchatshare和example.com/page?id1fromfeed實(shí)際上內(nèi)容一樣。為了提升緩存命中率我會先對 URL 做一下規(guī)整去掉utm_、spm、ref等追蹤參數(shù)再作為緩存鍵。但這個(gè)規(guī)則不能太激進(jìn)否則會把帶不同錨點(diǎn)的同頁誤判成同一篇影響準(zhǔn)確性。實(shí)際工程里只去掉utm_前綴的 query 參數(shù)就夠了。5. 適配后的驗(yàn)證鏈路與擴(kuò)展建議5.1 測試樣例怎么設(shè)計(jì)鏈接預(yù)覽功能一定要有一張“測試頁清單”。我的做法是在本地搭一個(gè)臨時(shí) HTML 頁面順便用三個(gè)線上頁面做冒煙測試。重點(diǎn)是覆蓋標(biāo)準(zhǔn) OG 頁面所有字段齊全只有 title 和 description 的頁面只有圖片鏈接用戶直接發(fā)圖片 URL的情況超長標(biāo)題和超長描述驗(yàn)證 UI 截?cái)?0K 以上 HTML 的大頁面驗(yàn)證性能。只有把這些跑完才敢說“適配完成”。對于 Flutter 側(cè)可以寫簡單的斷言測試expect(result.title, isNotEmpty)。但原生網(wǎng)絡(luò)請求在單元測試環(huán)境跑不了我一般用集成測試在鴻蒙模擬器或真機(jī)上跑。注意模擬器上部分站點(diǎn)會返回與真機(jī)不同的頁面最壞的情況是地域性網(wǎng)頁所以還要在真實(shí)設(shè)備上過一遍。測試數(shù)據(jù)不能寫死因?yàn)榫W(wǎng)絡(luò)頁面隨時(shí)可能改版建議保留一份本地 mock 的 HTML 樣例用于斷言解析邏輯的穩(wěn)定性。5.2 性能和合規(guī)上的額外建議性能上我強(qiáng)烈建議限制抓取頁面大小。某些網(wǎng)站的 HTML 有幾 MB全量下載只會拖慢卡片響應(yīng)而且只為了幾個(gè) meta 標(biāo)簽非常不劃算?？梢栽谠鷤?cè)讀取前 128KB 就截?cái)嘁驗(yàn)?meta 基本都在 head 里這樣能節(jié)省大量流量。實(shí)現(xiàn)時(shí)判斷響應(yīng)體長度超過閾值就只保留前段。如果截?cái)嗪蟀l(fā)現(xiàn)沒有og:image可以再嘗試從后文中提取但多數(shù)情況不需要。安全合規(guī)上鏈接預(yù)覽的本質(zhì)是把用戶看到的鏈接信息交給目標(biāo)站點(diǎn)來換取元數(shù)據(jù)所以不能在不告知用戶的情況下自動掃描聊天記錄里的所有鏈接。產(chǎn)品上應(yīng)該做到用戶發(fā)布或點(diǎn)擊消息時(shí)觸發(fā)抓取而不是后臺批量抓取。另外如果未來把抓取邏輯放到服務(wù)端一定要做 SSRF 防護(hù)禁止請求內(nèi)網(wǎng) IP?？蛻舳讼鄬︼L(fēng)險(xiǎn)低也不能掉以輕心把 URL 的 scheme 限定為 http、https防止file://這類偽協(xié)議。數(shù)據(jù)緩存方面還要注意 GDPR 和本地法規(guī)對個(gè)人信息的最小化要求。鏈接預(yù)覽拿到的只是網(wǎng)頁公開元信息本身不算個(gè)人信息但如果結(jié)合消息發(fā)送者 ID 長期保存就可能被認(rèn)定為個(gè)人行為畫像存儲。更穩(wěn)妥的做法是只緩存 URL 與元數(shù)據(jù)不關(guān)聯(lián)到用戶 ID并且設(shè)置過期清理。5.3 后續(xù)擴(kuò)展方向這套適配思路可以復(fù)制到其他“解析型”Flutter 插件在本地的原生目錄補(bǔ)一個(gè) ArkTS 實(shí)現(xiàn)保持 channel 名和返回結(jié)構(gòu)不變。如果只是抓標(biāo)題和圖片也可以考慮用鴻蒙的系統(tǒng)網(wǎng)頁組件做一些輕量降級。更進(jìn)一步的玩法是把鏈接預(yù)覽做成服務(wù)端聚合接口客戶端只拉接口這樣多端體驗(yàn)完全一致也更方便統(tǒng)計(jì)點(diǎn)擊率。但這個(gè)改造要把抓取延遲從客戶端轉(zhuǎn)移到服務(wù)端需要權(quán)衡 CDN 緩存策略。另外鴻蒙生態(tài)一直在完善 Flutter 插件的標(biāo)準(zhǔn)能力未來會有更多三方庫支持原生實(shí)現(xiàn)。作為開發(fā)者我們要做的就是保持“橋接層薄、解析層獨(dú)立”的架構(gòu)把抓取邏輯盡量收斂在原生側(cè)Dart 側(cè)只保留 UI 和狀態(tài)管理。這樣即使原庫升級適配代碼的維護(hù)范圍也很小。我在自己維護(hù)的 fork 分支里就經(jīng)常用 diff 工具監(jiān)聽原庫變更只合并 Dart 層的 bugfix原生目錄始終自己維護(hù)避免被上游改動帶跑偏。我個(gè)人在實(shí)際操作中的體會是鏈接預(yù)覽更值得投入的是“回退規(guī)則”和“緩存”而不是花哨的動畫。很多頁面并不規(guī)范只有把基礎(chǔ)規(guī)則做扎實(shí)用戶才看不出哪條鏈接是自動抓的。后續(xù)我會把這次適配的橋接層抽成一個(gè)模板遇到同類型的抓取插件可以直接套用省去重復(fù)踩坑的時(shí)間。