接手一個(gè)老前端項(xiàng)目時(shí)我在代碼里翻到這樣一行var url document.reference;。運(yùn)行起來永遠(yuǎn)是undefined但沒人改因?yàn)楹髞斫恿艘粋€(gè)兜底邏輯。評(píng)論區(qū)留著一條三年前的留言“reference 是哪個(gè) API是不是寫錯(cuò)了”——確實(shí)寫錯(cuò)了他想寫的是document.referrer。這類把referrer記成reference的Case我見過太多次?？删瓦@么一個(gè)拼寫問題牽引出的是整片和document引用相關(guān)的知識(shí)體系對(duì)象的引用獲取方式、來源頁面的引用讀取、跨文檔訪問、框架里的引用陷阱……這篇文章我想把圍繞document.reference這個(gè)易錯(cuò)詞能展開的東西一次講透。如果你是剛接觸 DOM 操作的新人這篇文章能幫你把document相關(guān)的各種引用概念梳理清楚如果你已經(jīng)寫了兩三年業(yè)務(wù)代碼里面那幾個(gè)iframe、Shadow DOM、跨域引用的坑應(yīng)該能讓你少加幾次班。1. 先說清楚document.reference 這個(gè)名字下藏著什么1.1 拼寫錯(cuò)誤背后真實(shí)的 API 是 document.referrer先說結(jié)論最直接瀏覽器標(biāo)準(zhǔn)里沒有document.reference這個(gè)屬性。你在控制臺(tái)敲document.reference得到的只會(huì)是undefined。那開發(fā)者為什么會(huì)記成這個(gè)拼法因?yàn)檎嬲苫畹膶傩越衐ocument.referrer——兩個(gè)r不是reference的rence。它返回的是當(dāng)前頁面從哪個(gè)地址跳轉(zhuǎn)過來的來源 URL也就是 HTTP Referer 頭的瀏覽器端暴露版本。注意 HTTP 標(biāo)準(zhǔn)頭拼的是Referer少一個(gè)rWeb API 屬性名referrer是完整拼寫兩邊都跟reference沒關(guān)系。這個(gè)屬性的典型場景是外站鏈接帶過來的流量統(tǒng)計(jì)、站內(nèi)來源判斷、回跳按鈕。比如你可能寫過類似邏輯const backUrl document.referrer; if (backUrl backUrl.includes(google.com)) { // 從谷歌搜索跳來的走特殊落地頁邏輯 }1.2 另一種理解把 document 當(dāng)成一個(gè)“引用”來討論如果否定拼寫錯(cuò)誤這個(gè)角度document.reference還能被解讀為另一個(gè)層面的問題——在 JavaScript 中document 作為全局對(duì)象的一個(gè)引用屬性它的獲取方式、傳遞方式、生命周期是什么樣的。這其實(shí)是更本質(zhì)的主題。我們?cè)诖a里到處直接用document但它本質(zhì)上是個(gè)全局變量掛在window對(duì)象上等價(jià)于window.document。出于代碼規(guī)范、隔離環(huán)境、跨模塊傳遞等需求我們經(jīng)常需要拷貝、傳遞、緩存這個(gè)引用或者通過其他路徑拿到它。這中間的規(guī)范和不規(guī)范組成了一套隱性的知識(shí)點(diǎn)。1.3 我會(huì)怎么拆解這篇文章既然輸入只有document.reference一個(gè)詞我打算按三條線把內(nèi)容串起來第一最容易誤寫的document.referrer它的業(yè)務(wù)價(jià)值、邊界條件和替代方案第二圍繞document對(duì)象本身的各種引用獲取路徑包括window.document、document.documentElement、ownerDocument、getRootNode()、iframe.contentDocument等第三前端框架時(shí)代document引用容易失控的地方以及我實(shí)際踩過的一些和引用相關(guān)的坑。2. 最容易混淆的 document.referrer業(yè)務(wù)價(jià)值與邊界條件2.1 來源引用的核心使用場景document.referrer的應(yīng)用面其實(shí)比很多人以為的廣。SSR 頁面可以做服務(wù)端來源校驗(yàn)SPA 可以做路由來源分析站長工具、訪問日志里也大量依賴這個(gè)字段。最常見的業(yè)務(wù)場景有三個(gè)渠道來源統(tǒng)計(jì)。市場投放的落地頁需要區(qū)分流量來自搜索引擎、社交媒體還是外鏈文章document.referrer是零成本方案。站內(nèi)跳轉(zhuǎn)回退。A 頁面跳 B 頁面B 頁面的“返回”按鈕如果直接用history.back()從站外直接進(jìn) B 時(shí)按鈕會(huì)失效配合document.referrer判斷有沒有站內(nèi)來源再?zèng)Q定按鈕行為。防盜鏈與來源校驗(yàn)。部分下載接口會(huì)校驗(yàn)Referer頭前端可以先用document.referrer做個(gè)初步判斷給出帶有明確提示的交互反饋。例如一個(gè)移動(dòng)端的活動(dòng)頁通常這么處理下載引導(dǎo)function isFromPartnerSite() { const ref document.referrer; if (!ref) return false; try { return new URL(ref).hostname.includes(partner.com); } catch (error) { return false; } }2.2 幾個(gè)容易踩的邊界情況這個(gè) API 看起來簡單實(shí)際限制一抓一把。我工作里碰到的至少有以下四類第一空字符串情況。直接刷新頁面、從瀏覽器收藏夾打開、地址欄手動(dòng)輸入 URLdocument.referrer都是空字符串不是null也不是undefined。判斷時(shí)一定要用!ref或者.length 0別寫ref null這種條件——你會(huì)發(fā)現(xiàn)永遠(yuǎn)不成立。第二HTTPS 頁面丟 Referrer。從 HTTPS 頁面跳轉(zhuǎn)到另外一個(gè)獨(dú)立域名的 HTTP 頁面時(shí)瀏覽器出于安全策略不會(huì)發(fā)送完整的 Referer 頭document.referrer會(huì)變成空。反之HTTP 頁面跳 HTTPS 頁面是正常的。所以就算前端拿到了一個(gè)非空來源也要做好為空時(shí)的兜底展示。第三SPA 路由切換導(dǎo)致 referrer 失靈。這是單頁應(yīng)用里最隱蔽的坑。用戶從運(yùn)營活動(dòng)頁點(diǎn)擊跳轉(zhuǎn)到你的 SPA 首頁document.referrer記錄的是這個(gè)運(yùn)營活動(dòng)頁。但是用戶進(jìn)入 SPA 之后內(nèi)部通過history.pushState連續(xù)切換了三個(gè)路由此時(shí)如果你在第三個(gè)路由頁讀取document.referrer拿到的還是最初那個(gè)運(yùn)營活動(dòng)頁地址因?yàn)槟愀緵]有觸發(fā)過真正的瀏覽器文檔級(jí)跳轉(zhuǎn)。pushState不會(huì)更新 referrer 值。第四iframe 嵌套和referrerpolicy影響。頁面里有第三方 iframe 時(shí)iframe 內(nèi)部頁面拿到的 referrer 受 iframe 標(biāo)簽上的referrerpolicy屬性控制可能被降級(jí)成只保留源信息origin-only甚至為空。這也是為什么很多第三方統(tǒng)計(jì)腳本要求嵌入方去掉referrerpolicy或使用no-referrer-when-downgrade默認(rèn)策略。2.3 丟失來源之后的替代方案document.referrer不行的時(shí)候業(yè)務(wù)上就不能靠它了。我做過的一個(gè)活動(dòng)頁需要精確記錄用戶是從哪個(gè)專題頁跳來的但頁面里嵌了兩個(gè)騰訊視頻的 iframe其中一個(gè) iframe 的referrerpolicyno-referrer是產(chǎn)品定死的導(dǎo)致那個(gè) iframe 里所有埋點(diǎn)都沒有來源信息。最后方案是由外層頁面通過postMessage把document.referrer注入到 iframe 內(nèi)部iframe 內(nèi)部打點(diǎn)統(tǒng)一走消息通道。類似這樣// 外層頁面 iframe.contentWindow.postMessage({ type: SOURCE_REFERRER, referrer: document.referrer }, *);// iframe 內(nèi)部 window.addEventListener(message, (event) { if (event.data event.data.type SOURCE_REFERRER) { window.__SOURCE_REFERRER__ event.data.referrer; } });雖然消息監(jiān)聽用了*不夠嚴(yán)謹(jǐn)線上環(huán)境建議換成具體的業(yè)務(wù)域名白名單但思路是通用的跨文檔來源信息丟失時(shí)用消息通道把上層文檔的引用信息傳遞下去。如果你依賴document.referrer做注冊(cè)轉(zhuǎn)化歸因我的建議是盡早做服務(wù)端兜底。前端 JS 里拿不到 referrer 時(shí)讓后端同學(xué)讀取 HTTP 請(qǐng)求里的Referer頭記錄下來兩邊對(duì)著看還原真實(shí)來源鏈路。3. 拿到 document 引用的所有正確姿勢(shì)3.1 全局引用window.document 和裸 document 的關(guān)系先說一個(gè)容易被人忽略的事實(shí)在瀏覽器環(huán)境里裸寫document和window.document完全等價(jià)因?yàn)閐ocument作為全局對(duì)象window的一個(gè)屬性存在。但你如果寫嚴(yán)格模式下的模塊代碼或者HTML里有個(gè)元素iddocument這種情況極少但確實(shí)存在命名沖突就來了。div iddocument我是div/div script console.log(window.document.nodeType); // 9Document 對(duì)象一切正常 console.log(document.nodeType); // 可能出問題 /script有iddocument的元素存在時(shí)瀏覽器會(huì)創(chuàng)建一個(gè)名為document的全局變量指向該元素覆蓋掉原有的對(duì)Document對(duì)象的引用。這種寫法在業(yè)務(wù)代碼里幾乎不會(huì)出現(xiàn)但瀏覽器插件或者第三方腳本注入時(shí)保不齊。規(guī)范的做法是在模塊作用域內(nèi)顯式聲明const doc window.document;這樣不管全局命名空間怎么被污染模塊里的doc都穩(wěn)妥指向正確的文檔對(duì)象。我們自己寫 SDK 時(shí)入口都先取一次const rootDocument window.document ?? document杜絕環(huán)境干擾。3.2 從具體元素反向拿引用ownerDocument 和 getRootNode()做復(fù)雜組件時(shí)經(jīng)常會(huì)拿到一個(gè) DOM 元素卻需要反過來拿它所屬的文檔。這時(shí)候element.ownerDocument就是標(biāo)準(zhǔn)答案。它返回元素的根節(jié)點(diǎn)所在文檔也就是這個(gè)元素屬于哪個(gè)Document。const button document.querySelector(#submitBtn); const doc button.ownerDocument; // 等價(jià)于 document在同一個(gè)文檔里有人問直接用document不就行了區(qū)別在 iframe 和 Shadow DOM 場景下變得明顯。比如在某個(gè) iframe 內(nèi)部拿到一個(gè)元素你在外層用document.querySelector根本找不到它但通過element.ownerDocument你能拿到那個(gè) iframe 內(nèi)部的文檔對(duì)象從而調(diào)用它的querySelector、createElement等方法。Shadow DOM 里則推薦用getRootNode()它比ownerDocument走得更深const shadowHost document.querySelector(#shadowHost); const shadowRoot shadowHost.shadowRoot; const innerBtn shadowRoot.querySelector(#innerBtn); // 在事件回調(diào)里this指向某個(gè)shadow DOM內(nèi)的元素 function onClick() { const rootNode this.getRootNode(); // 當(dāng) rootNode 是 ShadowRoot 時(shí)說明元素在shadow樹里 // 當(dāng) rootNode 是 Document 時(shí)說明元素在普通DOM樹里 if (rootNode.nodeType 11) { // DocumentFragmentShadowRoot rootNode.host; // 拿到shadow宿主元素 } }寫 Web Components 或者復(fù)雜彈窗組件時(shí)這兩個(gè) API 是繞不開的。3.3 跨文檔引用iframe 的 contentDocument 與 contentWindowiframe 的場景是 document 引用最容易出問題的地方也是面試高頻題。拿到 iframe 內(nèi)部文檔的路徑是先通過 DOM API 拿到 iframe 元素對(duì)象再訪問它的contentDocument屬性或先用contentWindow得到 iframe 窗口對(duì)象再取contentWindow.document。const iframeEl document.querySelector(#myIframe); // 方式一直接從元素節(jié)點(diǎn)訪問 const innerDoc iframeEl.contentDocument; // 方式二先拿窗口對(duì)象再取 document const innerDoc2 iframeEl.contentWindow.document;這兩種方式拿到的都是 iframe 內(nèi)部文檔的引用操作它內(nèi)部 DOM 和操作主文檔沒什么區(qū)別。但你得隨時(shí)記住同源限制iframe 加載了跨域頁面時(shí)contentDocument是null訪問contentWindow.document會(huì)直接拋 SecurityError。線上典型報(bào)錯(cuò)是這樣的Uncaught DOMException: Blocked a frame with origin https://example.com from accessing a cross-origin frame.遇到跨域 iframe 需要通信只能走postMessage沒有別的辦法。我在實(shí)際項(xiàng)目里維護(hù)過一個(gè)跨域管理后臺(tái)主站和 iframe 子應(yīng)用完全兩個(gè)域名所有聯(lián)動(dòng)都包裝了一層postMessagePromise 工具function sendMessageToIframe(iframeEl, message) { return new Promise((resolve) { const channel new MessageChannel(); channel.port1.onmessage (event) resolve(event.data); iframeEl.contentWindow.postMessage(message, https://subapp.example.com, [channel.port2]); }); }MessageChannel 相比直接監(jiān)聽message事件的好處是響應(yīng)不必約定全局事件名每個(gè)請(qǐng)求對(duì)應(yīng)一個(gè)獨(dú)立消息通道調(diào)試時(shí)清爽很多。3.4 文檔內(nèi)常用子引用documentElement 與 body很多新手分不清document.documentElement和document.body。前者是html元素后者是body元素。頁面高度、滾動(dòng)高度、根字體大小這些全局值基本都掛在document.documentElement上。// 整個(gè)頁面的完整高度 const fullHeight document.documentElement.scrollHeight; // 視口高度 const viewHeight document.documentElement.clientHeight; // 根字體大小用于 rem 布局換算 const rootFontSize parseFloat(getComputedStyle(document.documentElement).fontSize);document.body則更多地用于往頁面末尾追加節(jié)點(diǎn)。比如動(dòng)態(tài)插入腳本時(shí)const script document.createElement(script); script.src https://cdn.example.com/lib.js; document.body.appendChild(script);這兩個(gè)引用在樣式和布局相關(guān)邏輯里是我使用頻率最高的 document 成員。有些兼容老代碼的場景還會(huì)判斷document.documentElement和document.body誰存在再操作因?yàn)槔碚撋辖馕鰰r(shí) body 還未生成。4. 框架時(shí)代里document 引用為什么容易“失控”4.1 React 的 ref 與全局 document 引用的互補(bǔ)React 開發(fā)者對(duì)ref很熟但對(duì)“全局 document 引用”的把握未必到位。React 的ref是組件內(nèi)部局部的 DOM 引用而document是跨組件全局的文檔引用。兩者互補(bǔ)但經(jīng)常打架。最典型的場景是事件監(jiān)聽。React 合成事件只掛在根容器上所以你在組件里監(jiān)聽document上的原生事件時(shí)必須自己管理生命周期。我用過一個(gè)輪詢外部數(shù)據(jù)的組件在useEffect里注冊(cè)了document的鍵盤事件useEffect(() { function handleKeyDown(event) { if (event.key Escape) { closeModal(); } } document.addEventListener(keydown, handleKeyDown); return () { document.removeEventListener(keydown, handleKeyDown); }; }, []);如果removeEventListener寫漏了或者依賴數(shù)組變化導(dǎo)致 effect 反復(fù)執(zhí)行document上會(huì)堆積無數(shù)事件監(jiān)聽一次按鍵觸發(fā)幾十個(gè)回調(diào)。排查方式是在 DevTools 的 Elements 面板選中document節(jié)點(diǎn)在 Event Listeners 里一個(gè)個(gè)看——但實(shí)際卡頓時(shí)你根本來不及看最好從一開始就在清理函數(shù)里做對(duì)稱釋放。4.2 Vue 3 里訪問 document 的時(shí)機(jī)陷阱Vue 3 的setup生命周期里組件實(shí)例還沒掛載完模板 DOM 還沒渲染。你在setup里直接操作document.getElementById大概率拿到null。正確做法是放到onMounted里import { onMounted } from vue; setup() { onMounted(() { document.getElementById(app-mount); // 此時(shí)才安全 }); }這是個(gè)基礎(chǔ)問題但新手經(jīng)常忽略。還有一種更容易出現(xiàn)在生產(chǎn)環(huán)境的情況你寫了一個(gè)工具庫既支持瀏覽器也支持服務(wù)端渲染SSR工具庫內(nèi)部直接使用了document。SSR 執(zhí)行時(shí)根本沒有document代碼直接拋 ReferenceError。處理方式是在模塊加載時(shí)做環(huán)境判斷const isBrowser typeof window ! undefined typeof window.document ! undefined; function getDocument() { if (isBrowser) { return window.document; } throw new Error(當(dāng)前環(huán)境無 DOM請(qǐng)?jiān)跒g覽器端調(diào)用); }4.3 跨 iframe 操作文檔引用時(shí)框架內(nèi)外的權(quán)責(zé)劃分實(shí)際業(yè)務(wù)里iframe 經(jīng)常是第三方系統(tǒng)嵌入主站。主站是 React/Vue 技術(shù)棧iframe 內(nèi)可能是完全不同的技術(shù)棧。這時(shí)候操作 iframe 內(nèi)部 document 就要想清楚邊界哪些行為由外層框架負(fù)責(zé)哪些由 iframe 內(nèi)部自己負(fù)責(zé)。我的原則是外層框架只負(fù)責(zé) iframe 元素的掛載、尺寸調(diào)整和消息通信絕不直接操作 iframe 內(nèi)部 DOM。原因很簡單一旦 iframe 內(nèi)部結(jié)構(gòu)升級(jí)外層代碼的 document 引用操作全部失效維護(hù)成本極高。所有內(nèi)部改動(dòng)都讓 iframe 內(nèi)自己的腳本處理外層需要什么數(shù)據(jù)通過消息協(xié)議要。舉個(gè)例子一個(gè)富文本編輯器 iframe// 外層框架獲取編輯器內(nèi)容 const editorIframe document.querySelector(#editorIframe); editorIframe.contentWindow.postMessage({ type: GET_CONTENT, requestId: req-001, }, *);// iframe 內(nèi)部監(jiān)聽請(qǐng)求并回傳 window.addEventListener(message, (event) { if (event.data.type GET_CONTENT) { const content document.body.innerHTML; event.source.postMessage({ requestId: event.data.requestId, content, }, event.origin); } });把 document 的引用使用邊界用消息協(xié)議劃開系統(tǒng)和系統(tǒng)之間就不會(huì)互相踩腳。5. 我踩過的 document 引用坑與排查習(xí)慣5.1 腳本順序造成的空引用document.body 為 null一個(gè)很常見的錯(cuò)誤是在head里內(nèi)聯(lián)腳本直接訪問document.body。因?yàn)榻馕龅絟ead時(shí)body還沒開始解析所以document.body是null。新手經(jīng)常這么寫!DOCTYPE html html head script document.body.style.backgroundColor red; // 報(bào)錯(cuò) Cannot set properties of null /script /head body /body /html解決方式有三種腳本放到/body之前監(jiān)聽DOMContentLoaded事件后再操作用document.documentElement先操作html但很多場景不符合預(yù)期。我自己調(diào)試第三方埋點(diǎn)腳本時(shí)遇到過廣告攔截插件提前把body替換掉的情況導(dǎo)致document.body上的屬性丟失。穩(wěn)妥做法是先存一個(gè)bodyRef并在DOMContentLoaded后重新獲取而不是假設(shè)document.body永遠(yuǎn)有效。5.2 document 引用緩存導(dǎo)致的內(nèi)存泄漏前端內(nèi)存泄漏排查很大一部分是 document 引用的不當(dāng)緩存。如果你在某個(gè)全局?jǐn)?shù)組里存了 DOM 元素引用而元素被移除后數(shù)組項(xiàng)沒有清理那整棵 DOM 子樹都回收不了。更隱蔽的是這么一種寫法// 某個(gè)全局配置對(duì)象 const globalConfig { root: document.getElementById(root), }; // 組件銷毀后globalConfig.root 仍然指向已經(jīng)移除的 DOM 節(jié)點(diǎn)這個(gè)節(jié)點(diǎn)的引用被全局對(duì)象持有即使頁面其他部分不再需要它垃圾回收也沒法把它標(biāo)記回收。時(shí)間一長大量遺留節(jié)點(diǎn)堆積頁面越來越卡。我排查線上卡頓問題時(shí)在 Memory 面板的 Heap snapshot 里搜索Document能看到一堆 Detached DOM 節(jié)點(diǎn)——就是這類引用沒清理的后果。修復(fù)思路是別把 DOM 節(jié)點(diǎn)引用放在長生命周期全局對(duì)象里或者組件銷毀時(shí)顯式置空globalConfig.root null;5.3 DevTools 里的引用查看技巧$0 和 monitorEvents實(shí)際排查問題時(shí)Chrome DevTools 提供了幾個(gè)和 document 引用直接相關(guān)的小工具我每五分鐘可能用到一次在 Elements 面板隨便點(diǎn)選一個(gè)元素控制臺(tái)里用$0可以直接拿到這個(gè)元素的引用不用再querySelector。用$_可以拿到控制臺(tái)最近一次表達(dá)式的結(jié)果。用monitorEvents(document, click)可以在控制臺(tái)實(shí)時(shí)打印所有 document 上的 click 事件確認(rèn)事件監(jiān)聽是否觸發(fā)、是否重復(fù)觸發(fā)。搜某個(gè)節(jié)點(diǎn)是誰引用的可以在控制臺(tái)執(zhí)行queryObject或直接在 Memory 面板篩選。有個(gè)排查重復(fù)埋點(diǎn)的經(jīng)歷就是靠monitorEvents定位的頁面上一次點(diǎn)擊被上報(bào)了兩次用monitorEvents(document, click)看到監(jiān)聽了兩次原生 click 事件最后在代碼庫里找到兩個(gè)不同文件各注冊(cè)了一次事件回調(diào)盯著同一個(gè) document 引用干活卻不自知。5.4 代碼編譯對(duì) document 引用的影響嚴(yán)格模式和壓縮混淆模塊打包時(shí)document作為全局變量會(huì)被直接引用不受嚴(yán)格模式影響。但有些壓縮工具會(huì)在局部作用域內(nèi)重命名變量如果你的代碼明確寫了window.document一般不會(huì)被重命名如果裸寫document某些老舊的打包配置可能會(huì)把它誤判為局部變量而做錯(cuò)誤優(yōu)化。萬幸現(xiàn)在主流打包器對(duì)新代碼的兼容都很好這個(gè)坑更多地出現(xiàn)在自己寫自定義構(gòu)建插件時(shí)。真正需要注意的反而是 TypeScript 的lib配置。如果你的 tsconfig 沒有配置lib: [dom]TS 編譯時(shí)不知道document是什么類型直接報(bào)Cannot find name document。這不是運(yùn)行時(shí)報(bào)錯(cuò)但能煩死一堆從 Node 轉(zhuǎn)前端的人。正確配置是{ compilerOptions: { lib: [ES2020, DOM, DOM.Iterable] } }5.5 我的排查順序和個(gè)人心得最終整理一下我遇到 document 相關(guān)異常時(shí)的排查鐵律按順序執(zhí)行九成問題十分鐘內(nèi)能定位先在瀏覽器控制臺(tái)敲document.referrer確認(rèn)當(dāng)前頁面的來源排除來源丟失的干擾再敲document.readyState判斷當(dāng)前文檔加載狀態(tài)是loading、interactive還是complete很多空引用問題是腳本執(zhí)行時(shí)機(jī)導(dǎo)致的Elements 面板看元素是否存在配合$0確認(rèn)引用是否為空console 面板執(zhí)行g(shù)etEventListeners(document)查看 document 上掛了多少監(jiān)聽器排查重復(fù)監(jiān)聽和泄漏最后 Memory 面板做一次 Heap snapshot搜索 Detached 節(jié)點(diǎn)確認(rèn)是否有 DOM 引用沒有釋放。這套順序幫我處理過至少五六起線上問題從來源丟失到內(nèi)存泄漏都有跑通。老實(shí)說document.reference這個(gè)拼寫錯(cuò)誤帶給我的收獲比當(dāng)時(shí)準(zhǔn)備寫的document.referrer用法多得多——它逼我把整條 document 引用鏈路的細(xì)節(jié)都過了一遍該踩的坑也踩了個(gè)遍。