第一次在微信小程序里寫(xiě)background-image: url(../../images/bg.png)的時(shí)候我以為這就是一句平平無(wú)奇的 CSS結(jié)果開(kāi)發(fā)者工具里一片空白真機(jī)上也是一片空白左上角倒是能看到小程序正常的標(biāo)題欄頁(yè)面背景就像被誰(shuí)抹掉了一樣。去社區(qū)一搜才發(fā)現(xiàn)這不是偶發(fā)問(wèn)題而是微信小程序長(zhǎng)期以來(lái)的一個(gè)“硬性規(guī)定”WXSS 里的 background-image 不支持使用本地圖片路徑。不管你是用相對(duì)路徑還是絕對(duì)路徑只要那張圖在小程序包內(nèi)統(tǒng)統(tǒng)不生效。我印象里這個(gè)限制從最早的版本就有至今也沒(méi)有放開(kāi)。很多剛接觸小程序的人都會(huì)在這里卡一下甚至有人誤以為是自己路徑寫(xiě)錯(cuò)了反復(fù)改了半天。這篇文章我就把這個(gè)坑徹底挖一遍先說(shuō)清楚為什么小程序要這么設(shè)計(jì)再給三種實(shí)際驗(yàn)證可行的解決方案base64 編碼、網(wǎng)絡(luò)圖片、以及我最推薦的 image 標(biāo)簽鋪底方案。每種方案我都會(huì)寫(xiě)清楚適用場(chǎng)景、操作步驟和注意事項(xiàng)最后再放一份常見(jiàn)問(wèn)題的排查清單。無(wú)論你是第一次寫(xiě)小程序還是被這個(gè)背景圖問(wèn)題折磨過(guò)一陣子這篇文章都能直接給你可抄的作業(yè)。1. 問(wèn)題根源為什么小程序不讓直接用本地圖片做背景1.1 網(wǎng)上說(shuō)的“不支持”到底卡在哪一環(huán)很多人的第一反應(yīng)是“微信小程序連個(gè)背景圖都不讓我用”其實(shí)準(zhǔn)確說(shuō)限制的只是WXSS 中 background-image 對(duì)本地路徑的引用并不是說(shuō)小程序不能展示本地圖片。你隨便在一個(gè)image標(biāo)簽里寫(xiě)image src/images/bg.png /圖片是能正常顯示的這一點(diǎn)從沒(méi)用過(guò)小程序的人可能不太理解但確實(shí)如此。問(wèn)題出在 WXSS 的編譯機(jī)制上。小程序雖然長(zhǎng)得像網(wǎng)頁(yè)但它的樣式文件并不是瀏覽器直接解析的而是由微信的開(kāi)發(fā)工具做了一層編譯轉(zhuǎn)換。background-image 里如果寫(xiě)了本地相對(duì)路徑編譯器無(wú)法像 Web 端那樣去服務(wù)器上把這個(gè)圖片資源取回來(lái)再對(duì)應(yīng)到 background-image 上于是它就直接把這個(gè)聲明忽略掉了。官方文檔里寫(xiě)得很明確background-image 可以使用網(wǎng)絡(luò)圖片或 base64或image/組件代替。我自己的理解是這個(gè)限制跟小程序的渲染架構(gòu)有關(guān)。小程序 WXML 最終會(huì)被編譯成一棵節(jié)點(diǎn)樹(shù)background-image 里的本地資源引用如果不經(jīng)過(guò) pack 階段特殊處理在原生渲染層里找不到對(duì)應(yīng)資源就會(huì)靜默失敗。官方?jīng)]有明確說(shuō)“永遠(yuǎn)不可能支持”但從目前各大版本更新來(lái)看這個(gè)問(wèn)題并沒(méi)有被提上日程所以短期內(nèi)繞行是唯一出路。1.2 除了 background-image還有哪些“本地資源禁區(qū)”既然提到這個(gè)限制索性把相關(guān)的“本地資源禁區(qū)”一起列出來(lái)免得踩完背景圖的坑又踩別的坑WXSS 中的 background-image不支持本地路徑只能網(wǎng)絡(luò)圖或 base64。image標(biāo)簽在部分場(chǎng)景下支持本地路徑但如果圖片太大或首次渲染時(shí)用到lazy-load會(huì)出現(xiàn)短暫占位空白。CSS 中的font-face本地字體同樣不支持直接用本地 ttf/woff 字體文件必須轉(zhuǎn)成 base64 或走網(wǎng)絡(luò)地址。cover-view中的 background-imagecover-view 本身是個(gè)特殊組件背景圖要用 image 組件來(lái)鋪純 CSS 背景同理會(huì)受限。所以這不是一個(gè)孤立問(wèn)題而是小程序這套封閉樣式體系里的一貫風(fēng)格凡是涉及樣式層引用本地靜態(tài)資源的都會(huì)被攔一道。反過(guò)來(lái)想這也是在逼開(kāi)發(fā)者把靜態(tài)資源外置到 CDN或者通過(guò)更“組件化”的方式去組織頁(yè)面樣式。2. 方案一base64 編碼曲線救國(guó)2.1 怎么把圖片轉(zhuǎn)成 base64 字符串base64 方案的思路很簡(jiǎn)單既然 WXSS 里不允許本地路徑那我直接把圖片轉(zhuǎn)成一大段 base64 文本塞進(jìn) url 里這樣就不再是“本地路徑引用”而是一個(gè)“內(nèi)聯(lián)資源”。把圖片轉(zhuǎn)成 base64 常見(jiàn)的方法有三種第一用 Node 腳本批量處理。如果你圖片數(shù)量多強(qiáng)烈建議用這種方式而不是一張張手動(dòng)操作。寫(xiě)一個(gè)簡(jiǎn)單的 Node 腳本const fs require(fs); const path require(path); const filePath path.join(__dirname, bg.png); const ext path.extname(filePath).replace(., ); const base64 fs.readFileSync(filePath).toString(base64); console.log(data:image/${ext};base64,${base64});控制臺(tái)會(huì)輸出一長(zhǎng)串 base64 字符串把它復(fù)制到 WXSS 里就可以了。第二用在線轉(zhuǎn)碼工具。圖片轉(zhuǎn) base64 的工具很多上傳圖片就能自動(dòng)生成適合臨時(shí)用一張圖的情況。我個(gè)人不太建議把大圖扔到在線工具里一是上傳下載麻煩二是沒(méi)必要的隱私風(fēng)險(xiǎn)哪怕是不敏感的圖片也盡量本地處理。第三直接用編輯器插件。VS Code 里有一些圖片轉(zhuǎn) base64 的插件右鍵圖片就能輸出 data URI操作起來(lái)最無(wú)腦適合不熟悉命令行的朋友。2.2 寫(xiě)進(jìn) WXSS 的正確姿勢(shì)與體積賬拿到 base64 字符串之后在 WXSS 里的寫(xiě)法是.page-bg { width: 100%; height: 100vh; background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...省略); background-size: cover; background-position: center; }注意幾個(gè)點(diǎn)data:image 后面跟的格式要和圖片實(shí)際格式一致PNG 就是image/pngJPEG 就是image/jpeg。字符串不要換行不要有多余空格否則可能出現(xiàn)解析異常。如果背景圖尺寸不大比如 10KB 以內(nèi)這個(gè)方案完全可行但如果是超過(guò) 100KB 的圖轉(zhuǎn)出來(lái)的 base64 文本會(huì)特別長(zhǎng)直接導(dǎo)致 WXSS 文件體積暴漲。這里有一個(gè)很實(shí)在的體積賬base64 編碼的膨脹率大約是 4/3也就是說(shuō)一張 50KB 的圖片轉(zhuǎn)成 base64 之后大約會(huì)變成 66KB 左右的文本。小程序主包限制是 2MB如果你只是為了一個(gè)背景圖就把包體撐大幾十 KB雖然不算致命但對(duì)包體敏感的項(xiàng)目來(lái)說(shuō)不劃算而且很沒(méi)必要。我自己在真實(shí)項(xiàng)目里只用 base64 方案處理兩種場(chǎng)景一種是首屏的關(guān)鍵背景圖小尺寸為了保證加載速度另一種是只有幾 KB 的小圖標(biāo)背景比如按鈕紋理、裝飾性小圖。大背景圖一律不用這個(gè)方案。3. 方案二網(wǎng)絡(luò)圖片路徑3.1 合法域名的配置流程第二種方案是直接把背景圖片放到服務(wù)器上然后用完整的 URL 來(lái)引用。這也是官方文檔里明確認(rèn)可的方式。在 WXSS 里寫(xiě).page-bg { background-image: url(https://your-cdn.com/images/bg.png); background-size: cover; }寫(xiě)法上跟 Web 端幾乎沒(méi)區(qū)別但小程序多做了一步限制使用網(wǎng)絡(luò)圖片前必須在微信公眾平臺(tái)配置 downloadFile 合法域名。這個(gè)域名配置在哪兒登錄微信公眾平臺(tái)進(jìn)入小程序的管理后臺(tái)找到“開(kāi)發(fā)”-“開(kāi)發(fā)設(shè)置”-“服務(wù)器域名”然后在downloadFile 合法域名一欄里添加你的圖片域名。注意域名必須是 HTTPS 協(xié)議微信從基礎(chǔ)庫(kù) 2.x 開(kāi)始強(qiáng)制要求 HTTPS。域名不能帶端口號(hào)必須是備案過(guò)的企業(yè)或個(gè)人主體域名。配置完成后通常過(guò)幾分鐘生效不用重新發(fā)布版本。如果不配置會(huì)怎樣開(kāi)發(fā)工具里如果勾選了“不校驗(yàn)合法域名”本地模擬可能正常但真機(jī)上直接白屏控制臺(tái)報(bào)錯(cuò)提示url not in domain list。這條很容易踩尤其是第一次真機(jī)調(diào)試的人。3.2 開(kāi)發(fā)調(diào)試時(shí)的“臨時(shí)豁免開(kāi)關(guān)”每次在開(kāi)發(fā)者工具里本地調(diào)試網(wǎng)絡(luò)圖片我建議先確認(rèn)一下工具右上角的“詳情”-“本地設(shè)置”里是否勾選了“不校驗(yàn)合法域名、web-view業(yè)務(wù)域名、TLS 版本以及 HTTPS 證書(shū)”。為什么說(shuō)它是“臨時(shí)豁免”因?yàn)榉奖闶钦娴姆奖愕右彩钦娴目?。勾選之后本地環(huán)境一切正常圖片加載得飛起你以為線上也沒(méi)問(wèn)題結(jié)果提交審核之后真機(jī)上一看圖片全掛了。這就是因?yàn)殚_(kāi)發(fā)者工具幫你把域名校驗(yàn)繞過(guò)了而真實(shí)環(huán)境是嚴(yán)格校驗(yàn)的。所以我的操作習(xí)慣是開(kāi)發(fā)階段可以勾選但每次準(zhǔn)備提審之前一定把勾選去掉用“真實(shí)環(huán)境”跑一遍所有涉及網(wǎng)絡(luò)圖片的頁(yè)面。別嫌麻煩真機(jī)白屏這種事在開(kāi)發(fā)工具里根本模擬不出來(lái)只有去掉勾選后才能暴露。網(wǎng)絡(luò)圖片方案的最大優(yōu)點(diǎn)是不占包體積背景圖再大也無(wú)所謂加載靠網(wǎng)絡(luò)帶寬。最大的缺點(diǎn)是依賴網(wǎng)絡(luò)弱網(wǎng)環(huán)境下圖片加載不出來(lái)頁(yè)面會(huì)顯得很簡(jiǎn)陋。如果要嚴(yán)謹(jǐn)一點(diǎn)可以配一個(gè) loading 占位背景色比如.page-bg { background-color: #f5f5f5; background-image: url(https://your-cdn.com/images/bg.png); background-size: cover; }這樣圖片沒(méi)加載出來(lái)的時(shí)候至少還有一層淺灰色墊底不會(huì)出現(xiàn)大面積刺眼空白。4. 方案三image 標(biāo)簽鋪滿模擬背景最推薦4.1 組件結(jié)構(gòu)怎么寫(xiě)這個(gè)方法是我現(xiàn)在的主力方案不管是從體驗(yàn)還是從擴(kuò)展性來(lái)說(shuō)都比前兩種舒服很多。思路是不用 background-image而是用一個(gè)絕對(duì)定位的image組件把頁(yè)面鋪滿再把業(yè)務(wù)內(nèi)容放到它上面。WXML 結(jié)構(gòu)大致如下view classpage-container image classpage-bg src/images/bg.png modeaspectFill / view classpage-content !-- 這里放按鈕、文字、列表等內(nèi)容 -- /view /view對(duì)應(yīng)的 WXSS.page-container { position: relative; width: 100%; height: 100vh; overflow: hidden; } .page-bg { position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: 0; } .page-content { position: relative; z-index: 1; }關(guān)鍵點(diǎn)有三個(gè)外層容器要position: relative背景 image 要position: absolute并設(shè)置z-index: 0內(nèi)容區(qū)要position: relative并設(shè)置z-index: 1保證內(nèi)容不會(huì)被背景圖蓋住。為什么我推薦這個(gè)方案因?yàn)樗@開(kāi)了小程序?qū)?background-image 的所有限制并且在 API 的豐富度上碾壓 CSS 背景圖。image 組件天然支持lazy-load、binderror、bindload這些事件背景圖加載失敗時(shí)可以兜底顯示占位圖加載成功時(shí)可以拿到圖片的信息繼續(xù)做處理。比如你想在背景圖上疊加一層半透明的蒙版直接在 image 和內(nèi)容區(qū)之間插一個(gè)全屏 view 設(shè)置background-color: rgba(0,0,0,0.3)就能實(shí)現(xiàn)這在 CSS 背景圖方案里反而要額外加一層。4.2 場(chǎng)景延展輪播背景、動(dòng)畫(huà)過(guò)渡和按鈕遮罩image 鋪底方案的擴(kuò)展性有多好我舉幾個(gè)真實(shí)遇到的場(chǎng)景場(chǎng)景一動(dòng)態(tài)切換背景圖加淡入淡出過(guò)渡。如果只是 CSS background-image切換背景時(shí)要處理過(guò)渡動(dòng)畫(huà)非常別扭但用 image 組件可以同時(shí)放兩個(gè) image 疊在一起通過(guò)opacity做交叉淡入淡出代碼寫(xiě)起來(lái)很直觀view classpage-container image classpage-bg src{{bgIndex 1 ? bg1 : bg2}} modeaspectFill / view classpage-content內(nèi)容/view /view配合 CSS transition 或者小程序動(dòng)畫(huà) API效果就很絲滑。場(chǎng)景二背景圖加文字遮罩和漸變。很多頁(yè)面設(shè)計(jì)是背景圖底部壓一條漸變色再放文字用來(lái)保證文字可讀性。用 CSS background-image 的話你得寫(xiě)多層漸變疊加代碼又長(zhǎng)又容易出兼容問(wèn)題。用 image 方案的話直接在 image 上方加一個(gè) view.page-mask { position: absolute; left: 0; right: 0; bottom: 0; height: 200rpx; background: linear-gradient(to top, rgba(0,0,0,0.6), transparent); }簡(jiǎn)潔清晰任何人接手代碼一看就懂。場(chǎng)景三處理頁(yè)面內(nèi)容超出屏幕的情況。如果背景圖想固定在屏幕上內(nèi)容可以滾動(dòng)那用 image 鋪底時(shí)要注意外層容器不能設(shè)成height: 100vh; overflow: hidden而是要讓背景圖position: fixed內(nèi)容正常滾動(dòng).page-bg { position: fixed; top: 0; left: 0; width: 100%; height: 100%; z-index: 0; } .page-content { position: relative; z-index: 1; min-height: 100vh; }這種方式在 iOS 端和 Android 端表現(xiàn)都比較穩(wěn)定我實(shí)際測(cè)試下來(lái)比滾動(dòng)時(shí)背景圖跟著跑要舒服得多。5. 動(dòng)態(tài)背景圖與內(nèi)聯(lián)樣式場(chǎng)景5.1 動(dòng)態(tài)背景圖可以這樣寫(xiě)前面說(shuō) base64 和網(wǎng)絡(luò)圖片方案都能滿足靜態(tài)背景需求但如果你的背景圖是動(dòng)態(tài)變的比如用戶切換主題、運(yùn)營(yíng)后臺(tái)配置的 Banner 圖那再用 WXSS 靜態(tài)寫(xiě)死就太呆板了。動(dòng)態(tài)背景圖有一個(gè)很巧妙的繞過(guò)方式把 background-image 寫(xiě)到元素的 style 屬性里。雖然 WXSS 里不能寫(xiě)本地背景圖但內(nèi)聯(lián) style 是可以接受 base64 字符串的。也就是說(shuō)你可以把圖片轉(zhuǎn)成 base64存到 data 里然后view classpage-bg stylebackground-image: url({{bgBase64}})/view這樣就能實(shí)現(xiàn)動(dòng)態(tài)切換背景圖而且不觸發(fā) WXSS 對(duì)本地路徑的限制。不過(guò)要再次提醒base64 方式僅適合小圖圖片一大data 字段本身的傳輸和渲染開(kāi)銷就會(huì)顯現(xiàn)進(jìn)入頁(yè)面時(shí)可能卡頓。如果是網(wǎng)絡(luò)圖片的動(dòng)態(tài)切換其實(shí)直接用前面 image 組件方案更省事綁一個(gè) src 就行連 base64 都不用轉(zhuǎn)image classpage-bg src{{bgUrl}} modeaspectFill /5.2 把背景圖方案升級(jí)成“圖片組件 遮罩層”架構(gòu)如果你負(fù)責(zé)的項(xiàng)目里背景圖出現(xiàn)頻率比較高或者未來(lái)可能有多種背景變體我建議你在項(xiàng)目初期就做一個(gè)背景容器組件把上面這套“image 遮罩層”封裝成通用能力。組件內(nèi)部提供兩個(gè)插槽或者兩個(gè)屬性一個(gè)接收背景圖 URL一個(gè)接收內(nèi)容節(jié)點(diǎn)。這樣做的收益在后期非常明顯當(dāng)運(yùn)營(yíng)想給不同節(jié)日配置不同背景圖、不同遮罩色時(shí)改動(dòng)只在數(shù)據(jù)層組件代碼一行不用動(dòng)。我在一個(gè)電商小程序項(xiàng)目里就是用的這種思路后臺(tái)配置的專題頁(yè)背景、橫幅圖、插畫(huà)全部走同一個(gè) background 容器組件業(yè)務(wù)方只需要傳圖片地址和一個(gè)可選的遮罩顏色即可。6. 常見(jiàn)問(wèn)題與排查實(shí)錄6.1 問(wèn)題速查表我把實(shí)際開(kāi)發(fā)中遇到過(guò)、以及身邊同事咨詢過(guò)的問(wèn)題整理成了下面的速查表方便你按圖索驥現(xiàn)象原因解決方案WXSS 里寫(xiě)本地背景圖無(wú)效頁(yè)面空白小程序限制 background-image 使用本地路徑改用 base64、網(wǎng)絡(luò)圖片或 image 組件鋪底開(kāi)發(fā)者工具能顯示真機(jī)白屏開(kāi)發(fā)者工具勾選了“不校驗(yàn)合法域名”去掉勾選后真機(jī)重測(cè)并配置合法域名網(wǎng)絡(luò)背景圖在部分安卓機(jī)上不顯示圖片域名 HTTPS 證書(shū)不受信任檢查證書(shū)鏈?zhǔn)欠裢暾褂谜?guī) CA 簽發(fā)的證書(shū)base64 字符串很長(zhǎng)編譯速度明顯變慢WXSS 文件體積過(guò)大大圖不要轉(zhuǎn) base64換 CDN 地址背景圖加載時(shí)有明顯白屏閃爍圖片未預(yù)加載加載過(guò)程無(wú)占位外層容器設(shè)置背景色或使用 image 的 bindload 事件頁(yè)面滾動(dòng)時(shí)背景圖跟隨滾動(dòng)出現(xiàn)縫隙background-attachment 在小程序里支持不完整使用 position: fixed 的 image 鋪底方案image 鋪底后按鈕和文字無(wú)法點(diǎn)擊背景圖 z-index 或 pointer-events 問(wèn)題內(nèi)容區(qū)設(shè)置 position: relative z-index: 1背景圖在 iPhone 上鋪不滿全屏底部 home indicator 區(qū)域高度計(jì)算不一致外層容器用 100vh 或動(dòng)態(tài)計(jì)算可用高度6.2 踩坑心得多說(shuō)兩句我在真實(shí)項(xiàng)目里的幾個(gè)感受這幾點(diǎn)常規(guī)文檔里不太會(huì)寫(xiě)到。第一如果項(xiàng)目里同時(shí)用了HBuilderX打包uni-app到微信小程序background-image 的“本地路徑限制”同樣適用。uni-app 在編譯的時(shí)候有可能幫你在開(kāi)發(fā)環(huán)境把本地圖片轉(zhuǎn)成 base64但在發(fā)布到小程序端之后行為就會(huì)回歸到微信原生限制。所以不要以為用了跨端框架就能繞過(guò)這個(gè)規(guī)則最終落地還是要回到微信小程序的基礎(chǔ)能力上。第二本地背景圖很多時(shí)與其一張張?zhí)幚砗团挪椴蝗绫M早統(tǒng)一成“背景容器組件 網(wǎng)絡(luò)圖片”的形式。我見(jiàn)過(guò)不少項(xiàng)目前期圖省事全用 base64 塞在 WXSS 里后期需求一變想換圖得跑到一堆樣式文件里找替換維護(hù)成本實(shí)在不低。第三審查員有時(shí)候會(huì)注意頁(yè)面首屏加載性能。如果你把一張 1MB 的大圖轉(zhuǎn)成 base64 塞進(jìn)代碼包真機(jī)上首屏渲染會(huì)明顯卡頓在審查階段容易被判定為“體驗(yàn)不佳”。所以如果是內(nèi)容型頁(yè)面的背景圖盡量走 CDN如果是啟動(dòng)頁(yè)這種對(duì)加載速度極度敏感的場(chǎng)景更要把圖片壓到 50KB 以內(nèi)再考慮 base64。我還想提一點(diǎn)和背景圖相關(guān)的衍生場(chǎng)景有些頁(yè)面需要頂部狀態(tài)欄區(qū)域的背景顏色融合這個(gè)時(shí)候只調(diào)背景圖是不夠的還需要?jiǎng)討B(tài)適配頂部導(dǎo)航欄的高度比如通過(guò)wx.getSystemInfoSync()獲取statusBarHeight把背景容器往上頂?shù)狡聊豁斏稀＿@個(gè)細(xì)節(jié)做不好背景圖會(huì)跟系統(tǒng)狀態(tài)欄之間出現(xiàn)一條突兀的色差帶我一開(kāi)始忽略過(guò)后來(lái)被 UI 設(shè)計(jì)師指著屏幕說(shuō)“這里有條縫”才專門做了處理。根據(jù)我個(gè)人的經(jīng)驗(yàn)最后再分享一個(gè)實(shí)用小技巧不管用哪種方案給背景圖所在容器設(shè)置一個(gè)background-color并讓它跟頁(yè)面整體色系接近這樣做的好處是即使圖片加載慢用戶看到的也不是刺眼的空白而是一個(gè)自然過(guò)渡的色塊。一個(gè)小小的background-color往往能避免大量“圖片沒(méi)加載出來(lái)”的投訴。背景圖這個(gè)問(wèn)題的本質(zhì)是小程序?yàn)榱吮ＷC渲染性能和資源管控犧牲了一部分 Web 端常見(jiàn)的靈活性。理解這一點(diǎn)之后順著它的規(guī)則去找方案其實(shí)并不復(fù)雜小圖用 base64大圖走 CDN追求體驗(yàn)和擴(kuò)展性就用 image 包底。三條路都能走通關(guān)鍵是別在一條路上死磕換個(gè)視角問(wèn)題往往就迎刃而解了。