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