做微信小程序時(shí)想給頁面加個(gè)背景圖第一反應(yīng)就是給外層view寫個(gè)background-image。我敢打賭你大概率寫過下面這段代碼.container { background-image: url(../../images/bg.png); background-size: cover; }編譯沒報(bào)錯(cuò)開發(fā)工具里偶爾能顯示一旦真機(jī)調(diào)試背景圖直接消失。就算開發(fā)工具里正常上傳體驗(yàn)版手機(jī)上一打開頁面背景還是空白一片。這個(gè)“微信小程序不支持使用本地圖片設(shè)置背景圖片”的問題幾乎每個(gè)小程序開發(fā)者都會(huì)踩一次。這篇內(nèi)容我會(huì)從根源講清楚為什么本地圖片不能直接當(dāng)背景再給出幾種真正能落地的替代方案包括base64、image組件模擬背景層、接口動(dòng)態(tài)下發(fā)等最后把真機(jī)調(diào)試中的常見坑也一并列出來。無論你是剛?cè)腴T小程序開發(fā)還是已經(jīng)寫了一段時(shí)間想徹底解決背景圖問題都可以直接參照里面的方案抄作業(yè)。1. 為什么直接把本地圖片路徑填進(jìn)background-image會(huì)失效1.1 先看一段“教科書式錯(cuò)誤”代碼很多新手教程里寫頁面背景第一步就是page { background-image: url(/images/bg.png); background-repeat: no-repeat; background-size: cover; }看起來沒有任何問題。路徑是從項(xiàng)目根目錄開始的絕對(duì)路徑文件也確實(shí)存在于/images/bg.png位置。但小程序編譯后WXSS里這個(gè)url()不會(huì)被解析成真實(shí)的文件訪問地址結(jié)果就是背景區(qū)域沒有任何圖片渲染。更迷惑的是開發(fā)工具模擬器上有時(shí)能看到有時(shí)看不到。因?yàn)殚_發(fā)者工具本質(zhì)上是運(yùn)行在瀏覽器環(huán)境里的模擬器對(duì)CSS的解析能力比真機(jī)原生渲染引擎寬松很多。你把同樣的代碼放到真機(jī)原生渲染線程按自己的規(guī)則解析WXSSurl()里的相對(duì)路徑根本沒有可訪問的文件上下文于是背景圖直接靜默失敗。1.2 小程序WXSS與瀏覽器CSS的關(guān)鍵區(qū)別瀏覽器里的CSSurl()會(huì)以當(dāng)前頁面URL為基準(zhǔn)去請(qǐng)求一個(gè)網(wǎng)絡(luò)資源。小程序不一樣頁面運(yùn)行在微信客戶端提供的原生渲染環(huán)境中WXSS編譯后在渲染線程里執(zhí)行它沒有一個(gè)“頁面URL”的概念所以u(píng)rl(相對(duì)路徑)這種寫法匹配不到代碼包里的實(shí)際文件。再深入一點(diǎn)小程序代碼包的圖片資源雖然被打包進(jìn)本地但渲染進(jìn)程不允許WXSS直接按路徑訪問本地文件系統(tǒng)。這跟瀏覽器加載本地圖片的邏輯完全不同瀏覽器里background-image: url(./bg.png)可行小程序里就是不行。官方也一直沒有開放這個(gè)能力短期內(nèi)也不會(huì)開放所以不要指望改改路徑、加個(gè)/前綴就能解決。1.3 官方限制的邊界哪些寫法確實(shí)有效搞清楚限制邊界很重要省得來回試錯(cuò)。實(shí)測(cè)下來下面幾種場(chǎng)景是可以正常顯示背景圖的background-image中使用網(wǎng)絡(luò)圖片地址url(https://cdn.xxx.com/bg.png)。background-image中使用base64編碼數(shù)據(jù)url(data:image/png;base64,...)。image組件直接引用本地圖片路徑image src/images/bg.png /。image組件引用網(wǎng)絡(luò)圖片、云存儲(chǔ)圖片都可以正常加載。也就是說限制主要集中在“WXSS里不能直接用本地圖片路徑做background-image”而image組件完全沒有這個(gè)限制。后面給的方案全部圍繞這幾條有效路徑展開。2. 四種替代方案哪一種更適合你的場(chǎng)景2.1 方案速覽與對(duì)比表格把常見的四種方案放到一張表里對(duì)比能更直觀地看出各自定位方案是否支持背景圖優(yōu)點(diǎn)缺點(diǎn)適用場(chǎng)景base64編碼寫入WXSS支持不依賴外部域名、離線可用、加載速度快體積膨脹約33%WXSS文件臃腫小尺寸裝飾圖、紋理圖、啟動(dòng)占位圖網(wǎng)絡(luò)圖片URL支持代碼量小、圖片可隨時(shí)換必須配置downloadFile合法域名依賴外鏈穩(wěn)定性有CDN/圖床、運(yùn)營活動(dòng)背景圖image組件絕對(duì)定位支持靈活、支持懶加載、可動(dòng)態(tài)切換需要額外寫層級(jí)和遮擋處理復(fù)雜背景層、數(shù)據(jù)驅(qū)動(dòng)的動(dòng)態(tài)背景云存儲(chǔ)/對(duì)象存儲(chǔ)托管支持穩(wěn)定、可后臺(tái)管理、適合生產(chǎn)環(huán)境需要接入云開發(fā)或第三方OSS正式運(yùn)營項(xiàng)目、多端復(fù)用背景圖2.2 選擇邏輯按圖片用途決定不是所有情況都用同一種方案選擇的關(guān)鍵是看圖片的使用方式。如果圖片是純靜態(tài)的裝飾元素比如一個(gè)固定的小紋理、毛玻璃底圖、按鈕背景基本不會(huì)變了直接轉(zhuǎn)base64寫進(jìn)WXSS最省事。不需要配置任何域名也不會(huì)有網(wǎng)絡(luò)加載延遲頁面一渲染背景就存在。如果圖片尺寸偏大或者以后要運(yùn)營替換千萬別用base64。一張幾百KB的圖編碼后接近400KBWXSS直接膨脹主包體積也遭不住。這種場(chǎng)景應(yīng)該把圖片傳到對(duì)象存儲(chǔ)或云存儲(chǔ)然后通過image組件渲染背景層或者用網(wǎng)絡(luò)地址寫進(jìn)background-image。如果業(yè)務(wù)背景圖跟數(shù)據(jù)強(qiáng)相關(guān)比如用戶自定義主題背景、不同商品有不同頭圖那必須用image組件加數(shù)據(jù)綁定用setData動(dòng)態(tài)切換src。用CSS方式做動(dòng)態(tài)背景會(huì)非常痛苦因?yàn)閎ackground-image的URL只能通過內(nèi)聯(lián)style動(dòng)態(tài)注入代碼可讀性和性能都不好。3. 三套可直接復(fù)用的實(shí)現(xiàn)方式3.1 本地小圖轉(zhuǎn)base64一次性寫死這是最直接的解法適合那種不會(huì)變的小圖片。比如一個(gè)200x200的紋理圖壓縮到50KB以內(nèi)轉(zhuǎn)成base64放進(jìn)WXSS頁面首屏就能直接顯示沒有任何請(qǐng)求開銷。圖片壓縮方面我習(xí)慣先用壓縮工具把圖壓到合適大小背景紋理一般壓到80KB以下就夠清晰了。然后轉(zhuǎn)base64你可以用線上工具也可以本地用Node跑一段腳本const fs require(fs); const path require(path); const filePath path.join(__dirname, bg.png); const mimeType image/png; // 根據(jù)實(shí)際格式改jpg是image/jpeg const base64Data fs.readFileSync(filePath).toString(base64); console.log(data:${mimeType};base64,${base64Data});把輸出的字符串完整復(fù)制到WXSS里page { height: 100%; background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...); background-size: cover; background-position: center; background-repeat: no-repeat; }需要注意兩個(gè)地方。第一url()引號(hào)內(nèi)側(cè)不要有多余換行或空格否則部分安卓機(jī)型會(huì)解析失敗。第二base64字符串非常長WXSS文件最好不要超過500KB否則開發(fā)者工具編譯會(huì)變慢上傳代碼包也容易超限。所以這個(gè)方法只適合小圖大圖還是用下面兩個(gè)方案。3.2 image組件模擬背景層最推薦的做法之所以說最推薦是因?yàn)閕mage組件本身就是小程序原生支持的對(duì)本地圖片、網(wǎng)絡(luò)圖片都友好不用轉(zhuǎn)碼、不用配置額外域名而且天然支持懶加載。實(shí)現(xiàn)思路是把一個(gè)image絕對(duì)定位到頁面底層再讓實(shí)際內(nèi)容層浮在上面。以本地圖片為例view classpage-wrapper image classpage-bg src/images/bg.png modeaspectFill / view classpage-content text這里是頁面內(nèi)容/text /view /view.page-wrapper { 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; }注意mode屬性的選擇。aspectFill會(huì)等比縮放并裁剪保證鋪滿整個(gè)容器且不變形背景圖首選。aspectFit會(huì)等比縮放并完整顯示但可能留有空白。scaleToFill會(huì)拉伸填充容易變形除非你故意要那種效果否則不建議用。這個(gè)方案還有個(gè)附帶好處image組件自帶binderror事件背景圖加載失敗時(shí)你可以捕獲并做降級(jí)處理這是CSS背景圖完全做不到的。3.3 動(dòng)態(tài)背景圖接口下發(fā)組件渲染運(yùn)營類小程序經(jīng)常需要后臺(tái)動(dòng)態(tài)配置背景圖比如節(jié)日換皮膚、不同用戶看到不同主題。如果背景圖是網(wǎng)絡(luò)圖片最簡(jiǎn)單的方式是后臺(tái)接口返回圖片URL前端綁定到image組件的src上image classpage-bg src{{themeBgUrl}} modeaspectFill /Page({ data: { themeBgUrl: }, onLoad() { this.loadTheme(); }, loadTheme() { // 模擬接口請(qǐng)求 setTimeout(() { this.setData({ themeBgUrl: https://cdn.xxx.com/theme/summer.jpg }); }, 100); } });如果你確實(shí)想用background-image也可以動(dòng)態(tài)拼內(nèi)聯(lián)styleview classpage-bg stylebackground-image: url({{themeBgUrl}});/view但這里有兩個(gè)坑。一是themeBgUrl必須是網(wǎng)絡(luò)地址絕對(duì)不能是本地路徑否則還是顯示不出來。二是如果URL里帶了特殊字符比如空格、中文參數(shù)只做簡(jiǎn)單的字符串拼接可能解析失敗建議在接口層直接返回已經(jīng)encode好的URL前端不加工。整體上動(dòng)態(tài)場(chǎng)景更推薦image組件方案因?yàn)閟etData的數(shù)據(jù)量更小、渲染性能更可控還方便加緩存和加載失敗占位。3.4 完整示例一個(gè)登錄頁的背景層實(shí)現(xiàn)拿常見的登錄頁舉例背景圖下面還要放表單要求背景不能擋住輸入框。完整結(jié)構(gòu)如下view classlogin-page image classbg-layer src{{bgUrl}} modeaspectFill / view classmask-layer/view view classlogin-box input placeholder手機(jī)號(hào) / input placeholder驗(yàn)證碼 / button登錄/button /view /view.login-page { position: relative; width: 100%; height: 100vh; overflow: hidden; } .bg-layer { position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: 0; } .mask-layer { position: absolute; top: 0; left: 0; width: 100%; height: 100%; background: rgba(0, 0, 0, 0.3); z-index: 1; } .login-box { position: relative; z-index: 2; padding: 40rpx; margin-top: 200rpx; }中間加一層半透明遮罩能讓背景圖壓暗一點(diǎn)前景的文字和輸入框更清晰。這也是很多C端小程序頁面背景的做法代碼量不大但視覺效果會(huì)專業(yè)很多。4. 排查與避坑真機(jī)表現(xiàn)不一致怎么辦4.1 開發(fā)工具正常真機(jī)背景卻空白這是最讓新手崩潰的情況。代碼在開發(fā)工具模擬器里顯示得很完美一傳到真機(jī)就空白。出現(xiàn)這個(gè)現(xiàn)象優(yōu)先排查兩方面第一確認(rèn)圖片引用方式。如果用的是background-image加本地路徑那沒救了必須換成上面三個(gè)方案之一。第二如果已經(jīng)用了image組件但真機(jī)還是空白看看控制臺(tái)有沒有報(bào)域名不合法。網(wǎng)絡(luò)圖片用image組件加載正式環(huán)境必須在微信公眾平臺(tái)后臺(tái)配置downloadFile合法域名域名的HTTPS證書也必須有效。開發(fā)工具里一般會(huì)開啟“不校驗(yàn)合法域名”所以本地能顯示真機(jī)必然攔截。另外提一個(gè)容易忽略的點(diǎn)本地圖片路徑盡量別用中文名稱。部分安卓機(jī)對(duì)中文路徑的解析有問題圖片可能加載不了。建議圖片文件統(tǒng)一用小寫英文命名。4.2 base64方案在部分安卓機(jī)型上的兼容問題base64雖然可以正常顯示背景圖但我在真機(jī)測(cè)試時(shí)遇到過個(gè)別安卓機(jī)型識(shí)別不了超長base64的background-image。準(zhǔn)確來說不是完全識(shí)別不了而是字符串超過一定長度后原生渲染組件解析超時(shí)或直接忽略。如果圖片不是特別小不建議走base64。如果非要用建議把圖片先壓到100KB以內(nèi)再轉(zhuǎn)base64。同時(shí)把WXSS里其他干擾樣式精簡(jiǎn)掉避免編譯后的WXSS體積過大。真的遇到問題優(yōu)先換成image組件方案這個(gè)方案在兩端表現(xiàn)最穩(wěn)定。4.3 包體積、setData與性能隱患本地圖片一旦多起來代碼包體積很容易告急。小程序主包限制是2MB一張高清背景圖動(dòng)輒幾百KB稍微多幾張就直接上傳失敗。哪怕只用了一張大圖base64后體積還會(huì)膨脹主包很容易超限。所以大圖一律走網(wǎng)絡(luò)地址或云存儲(chǔ)。image組件引用網(wǎng)絡(luò)圖時(shí)并不占用包體積只需要保證圖片地址長期有效。還有一個(gè)隱蔽問題動(dòng)態(tài)背景用setData塞一個(gè)超長URL雖然一般不會(huì)觸發(fā)1MB數(shù)據(jù)量限制但如果數(shù)據(jù)里混了其他大字段比如表單內(nèi)容、日志列表就可能報(bào)錯(cuò)。動(dòng)態(tài)背景圖的URL盡量放在獨(dú)立字段里別混在復(fù)雜嵌套對(duì)象中一起setData。4.4 背景圖加載閃白與占位處理網(wǎng)絡(luò)圖片加載需要時(shí)間如果沒有任何處理用戶會(huì)先看到白底然后圖片突然“崩”出來體驗(yàn)比較差。解決辦法是在背景圖位置先放一個(gè)底色和圖片主色調(diào)接近比如深色背景頁就加background-color: #1a1a1a。這樣圖片沒加載完時(shí)至少不是刺眼的白色。如果業(yè)務(wù)要求高可以監(jiān)聽image組件的bindload事件圖片加載完后再把內(nèi)容層淡入image classbg-layer src{{bgUrl}} modeaspectFill bindloadonBgLoaded /Page({ data: { bgLoaded: false }, onBgLoaded() { this.setData({ bgLoaded: true }); } });配合一個(gè)簡(jiǎn)單的過渡class就能做到“先底色、后漸顯”的效果體驗(yàn)會(huì)好很多。4.5 動(dòng)態(tài)內(nèi)聯(lián)style的隱藏坑有些同學(xué)還是會(huì)執(zhí)著于動(dòng)態(tài)background-image這里把坑說透。小程序里動(dòng)態(tài)內(nèi)聯(lián)style支持background-image但URL必須是網(wǎng)絡(luò)地址而且部分安卓端對(duì)URL里的括號(hào)、空格之類特殊字符非常敏感。接口返回的圖片地址如果是從第三方圖床拿的可能帶簽名參數(shù)舉個(gè)例子https://cdn.xxx.com/bg.jpg?signabc123expire1710000000這種地址直接放進(jìn)stylebackground-image: url({{url}})如果URL里的參數(shù)拼接不夠規(guī)范真機(jī)上可能只能顯示一部分甚至完全空白。正確做法是先做一次URL編碼或者統(tǒng)一由后端返回一個(gè)干凈無特殊字符的短鏈。更穩(wěn)妥的方式仍然是image組件它內(nèi)部做了更成熟的解析和容錯(cuò)基本不會(huì)出現(xiàn)這種問題。5. 最后一點(diǎn)使用習(xí)慣上的經(jīng)驗(yàn)總結(jié)我自己的習(xí)慣項(xiàng)目里所有頁面背景圖統(tǒng)一用image組件加絕對(duì)定位做背景層本地業(yè)務(wù)圖標(biāo)用image標(biāo)簽只有純裝飾小紋理才考慮base64。這樣團(tuán)隊(duì)協(xié)作時(shí)新人接手代碼也不容易踩背景圖不顯示的坑。再分享一個(gè)小技巧如果背景只是一些幾何紋理、漸變或簡(jiǎn)單的裝飾線條很多情況下根本不用切圖。直接用純CSS漸變、linear-gradient、radial-gradient加background-color就能實(shí)現(xiàn)不錯(cuò)的效果。這樣既不會(huì)碰到本地圖片限制也不需要網(wǎng)絡(luò)加載體積幾乎為零渲染速度最快。我后來很多頁面的底紋背景都改用CSS漸變模擬了效果比預(yù)想中好還省掉了一堆圖片資源。微信小程序這個(gè)“本地圖片不能直接做背景圖”的限制初看很反直覺但換一個(gè)思路把它當(dāng)成一次架構(gòu)設(shè)計(jì)的提醒背景圖本來就是展示層資源跟業(yè)務(wù)數(shù)據(jù)解耦才是更合理的做法。希望這篇內(nèi)容能幫你徹底繞開這個(gè)坑。