uni-app 跨端開發注意事項

H5正常但App異常的可能性

1. css異常：
2. 不支援的選擇器 非H5端不支援*選擇器；

body的元素選擇器請改為page，同樣，div和ul和li等改為view、span和font改為text、a改為navigator、img改為image...

• webview瀏覽器相容性

vue頁面在App端，預設是被系統的webview渲染的（不是手機自帶瀏覽器，是rom的webview），在較老的手機上，比如Android4.4、5.0或iOS8，很多css是不支援的，所以不要使用太新的css，會導致介面異常。

注意這不意味著不能使用flex，Android4.4也支援flex，只是不要使用太新的css。

可以找Android4.4手機或使用pc模擬器實際測試下，大多數國產Android模擬器都是4.4或5.0。

從 uni-app 2.5.3 起，Android端支援引入騰訊x5瀏覽器核心，可以抹平低端Android的瀏覽器相容性問題，詳見x5使用指南

小程式不存在瀏覽器相容問題，它自帶了一個很大的Webview。所以如果你的H5和小程式介面正常，而Android低端機App介面異常，且App沒有使用x5引擎，那基本就可以判定是因為css相容性。

app端nvue頁面，不存在瀏覽器相容問題，它自帶一個統一的原生渲染引擎，不依賴webview。

Android4.4對應的webview是chrome37。各端瀏覽器核心的詳情查閱，參考：關於手機webview核心、預設瀏覽器、各家小程式的渲染層瀏覽器的區別和相容性

• 原生元件層級問題 H5沒有原生元件概念問題，非H5端有原生元件並引發了原生元件層級高於前端元件的概念，要遮擋video、map等原生元件，請使用cover-view元件。
• 使用了非H5端不支援的API 小程式和App的js執行在jscore下而不是瀏覽器裡，沒有瀏覽器專用的js物件，比如document、xmlhttp、cookie、window、location、navigator、localstorage、websql、indexdb、webgl等物件。

如果你的程式碼沒有直接使用這些，那很可能是引入的三方庫使用了這些。如果是後者，去外掛市場搜尋替代方案。要知道非H5端的js是執行在一個獨立的js core或v8下，並不是執行在瀏覽器裡。

從HBuilderX 2.6起，App端新增了renderjs，這是一種執行在檢視層的js，vue頁面透過renderjs可以操作瀏覽器物件，進而可以讓基於瀏覽器的庫直接在uni-app的App端執行，諸如echart、threejs，詳見：

1. 使用了非H5端不支援的vue語法，受小程式自定義元件限制的寫法，詳見
2. 不要在引用元件的地方在元件屬性上直接寫 style="xx"，要在元件內部寫樣式
3. url(//alicdn.net)等路徑，改為url()，因為在App端//是file協議
4. 很多人在H5端聯網時使用本地測試服務地址(localhost或127.0.0.1)，這樣的聯網地址手機App端是無法訪問的，請使用手機可訪問的IP進行聯網

H5正常但小程式異常的可能性

1. 同上
2. v-html在h5和app-vue(v3編譯模式)均支援，但小程式不支援
3. 小程式要求連線的網址都要配白名單

小程式正常但App異常的可能性

vue頁面在App端的渲染引擎預設是系統webview（不是手機自帶瀏覽器，是rom的webview），在較老的手機上，比如Android4.4、5.0或iOS8，一些新出的css語法是不支援的。注意這不意味著不能使用flex，Android4.4也支援flex，只是不要使用太新的css。可以找Android4.4手機或使用pc模擬器實際測試下，大多數國產Android模擬器都是4.4或5.0。

小程式不存在瀏覽器相容問題，它內建了幾十M自己的定製webview。所以如果你的H5和小程式介面正常，而App介面異常，大多是因為css相容性。

解決這類問題：

1. 放棄老款手機支援
2. 不用使用太新的css語法，可以在caniuse查詢
3. 從 uni-app 2.5.3 起，Android端支援引入騰訊x5瀏覽器核心，可以抹平低端Android的瀏覽器相容性問題，詳見x5使用指南

小程式或App正常，但H5異常的可能性

1. 在 uni-app 2.4.7 以前，H5端不支援微信小程式自定義元件，即wxcomponets下的元件，此時可能產生相容問題。從 2.4.7 起，H5也支援微信自定義元件，不再存在這這方面相容問題。
2. App端使用了App特有的API和功能，比如plus、Native.js、subNVue、原生外掛等
3. 使用了小程式專用的功能，比如微信卡卷、小程式外掛、微信小程式雲開發。對於雲開發，建議使用可跨端的uniCloud。

App正常，小程式、H5異常的可能性

1. 程式碼中使用了App端特有的plus、Native.js、subNVue、原生外掛等功能

使用 Vue.js 的注意

1. uni-app 基於Vue 2.0實現，開發者需注意Vue 1.0 -> 2.0 的使用差異，詳見從 Vue 1.x 遷移
2. data 屬性必須宣告為返回一個初始資料物件的函式；否則頁面關閉時，資料不會自動銷燬，再次開啟該頁面時，會顯示上次資料 //正確用法，使用函式返回物件 data() { return { title: 'Hello' } } //錯誤寫法，會導致再次開啟頁面時，顯示上次資料 data: { title: 'Hello' }
3. 在微信小程式端，uni-app 將資料繫結功能委託給Vue，開發者需按Vue 2.0的寫法實現資料繫結，不支援微信小程式的資料繫結寫法，故如下寫法不支援： <view id="item-{{id}}"></view>需修改為： <view v-bind:id="'item-' + id "></view>

區別於傳統 web 開發的注意

你之前可能習慣自由的web開發，但目前各家小程式都有很多限制。 當然限制是為了在框架層更好的最佳化使用者體驗，所以小程式的體驗要優於web。 並且這些限制只是寫法的限制，並不影響功能。 如果你做過微信小程式開發，對這些限制應該已經很瞭解了。如果沒有做過小程式，請仔細閱讀本節。

1. JS注意非H5端，不能使用瀏覽器自帶物件，比如document、window、localstorage、cookie等，更不能使用jquery等依賴這些瀏覽器物件的框架。因為各家小程式快應用都不支援這些物件。沒有這些瀏覽器自帶物件並不影響業務開發，uni提供的api足夠完成業務。uni的api在編譯到web平臺執行時，其實也會轉為瀏覽器的js api。App端若要使用操作window、document的庫，需要透過renderjs來實現。uni的api是多端可用的。在條件編譯區，每個平臺的專有api也可以使用，比如wx.、plus.等api可以分別在微信下和app下使用。出於降低小程式向uni-app遷移成本的考慮，wx的api在app裡也可以直接執行，比如寫wx.requst和uni.requst是一樣的，但仍然建議僅在微信的條件編譯區使用wx的api。
2. Tag注意uni-app的tag同小程式的tag，和HTML的tag不一樣，比如div要改成view，span要改成text、a要改成navigator。出於降低h5應用向uni-app遷移成本的考慮，寫成div、span也可以執行在app和小程式上，因為uni-app編譯器會把這些HTML標籤編譯為小程式標籤。但仍然建議養成新習慣。
3. Css注意雖然大部分css樣式在微信小程式和app中都可以支援，但推薦使用flex佈局模型，這種佈局更靈活高效且支援更多平臺(比如nvue、快應用只支援flex佈局)單位方面，uni-app預設為rpx。這是一種可跨端的通用單位 詳見
4. 工程目錄注意每個要顯示的頁面，都要放到pages目錄下，新建一個頁面所在的目錄，然後放同名目錄的vue檔案，比如project/pages/lista/lista.vue，並且在pages.json裡配置。這與小程式的策略相同。自定義元件，放到component目錄靜態資源如圖片，固定放到static目錄下。這是webpack、mpvue的規則
5. 資料繫結方式的注意uni-app 基於Vue 2.0實現，開發者需注意Vue 1.0 -> 2.0 的使用差異，詳見從 Vue 1.x 遷移
6. 每個頁面支援使用原生title，首頁支援使用原生底部tab，這些是要在pages.json裡配置，這些並不是vue頁面的一部分。當然vue裡的js api也可以動態修改原生title
7. 雖然使用vue，但在app和小程式裡，不是spa而是mpa
8. 位置座標系統一為國測局座標系gcj02，這種座標系可以被多端支援。老版5+的百度定位和百度地圖使用的是百度私有座標系bd09ll，這種座標系需要轉換。新版uni-app裡的百度地圖已經預設改為gcj02。高德地圖不受影響，一直是gcj02

H5 開發注意

• H5 釋出到伺服器注意：配置發行後的路徑（發行在網站根目錄可不配置），比如發行網站路徑是 ，在 manifest.json 檔案內編輯 h5 節點，router 下增加 base 屬性為 html5

• 點選選單 發行-> H5在當下專案下的 unpackage/dist/build/h5 目錄找到出的資源，部署伺服器（或者使用本地伺服器預覽）
• 引用第三方 js 的方式：透過 npm 引入（透過條件編譯，只有是 h5 平臺才 import 相應的庫）在 manifest.json 檔案編輯 h5 節點的 template 屬性，填寫 html 模版路徑，在 html 模版裡面可以使用 script 的方式引入三方的 js，如下示例是加了百度統計的 html 模板部分程式碼，模版全部程式碼可參考：自定義模板... <body> <noscript> <strong>Please enable JavaScript to continue.</strong> </noscript> <div id="app"></div> <!-- built files will be auto injected --> <script> var _hmt = _hmt || []; (function() { var hm = document.createElement("script"); hm.src = " var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(hm, s); })(); </script> </body> ...
• H5 版 uni-app 全支援 vue 語法，所以可能造成部分寫法在 H5 端生效，在小程式或 App 端不生效。
• H5 校驗了更嚴格的 vue 語法，有些寫法不規範會報警，比如： data 後面寫物件會報警，必須寫 function；不能修改 props 的值；元件最外層 template 節點下不允許包含多個節點等。
• 編譯為 H5 版後生成的是單頁應用（SPA）。
• 如果遇到跨域造成js無法聯網，注意網路請求（request、uploadFile、downloadFile等）在瀏覽器存在跨域限制，解決方案有詳見：uni-app H5跨域問題解決方案（CORS、Cross-Origin） - DCloud問答
• APP 和小程式的導航欄和 tabbar 均是原生控制元件，元素區域座標是不包含原生導航欄和 tabbar 的；而 H5 裡導航欄和 tabbar 是 div 模擬實現的，所以元素座標會包含導航欄和tabbar的高度。為了優雅的解決多端高度定位問題，uni-app 新增了2個css變數：--window-top 和 --window-bottom，這代表了頁面的內容區域距離頂部和底部的距離。舉個例項，如果你想在原生tabbar 上方懸浮一個選單，之前寫 bottom:0。這樣的寫法編譯到 h5 後，這個選單會和 tabbar 重疊，位於螢幕底部。而改為使用 bottom:var(--window-bottom)，則不管在 app 下還是在h5下，這個選單都是懸浮在 tabbar 上浮的。這就避免了寫條件編譯程式碼。當然仍然也可以使用 H5 的條件編譯處理介面的不同。
• CSS 內使用 vh 單位的時候注意 100vh 包含導航欄，使用時需要減去導航欄和 tabBar 高度，部分瀏覽器還包含瀏覽器操作欄高度，使用時請注意。
• 正常支援 rpx，px 是真實物理畫素。暫不支援透過設 manifest.json 的 "transformPx" : true，把 px 當動態單位使用。
• 使用羅盤、地理位置、加速計等相關介面需要使用 https 協議，本地預覽（localhost）可以使用 http 協議。
• PC 端 Chrome 瀏覽器模擬器裝置測試的時候，獲取位置 API 需要連線谷歌伺服器。
• 元件內（頁面除外）不支援 onLoad、onShow 等頁面生命週期。
• 為避免和內建元件衝突，自定義元件請加上字首（但不能是 u 和 uni）。比如可使用的自定義元件名稱：my-view、m-input、we-icon，例如不可使用的自定義元件名稱：u-view、uni-input，如果已有專案使用了可能造成衝突的名稱，請修改名稱，另外微信小程式下自定義元件名稱不能以 wx 開頭。

微信小程式開發注意

• 微信小程式當前bug列表
• 微信小程式更新日誌

支付寶小程式開發注意

• 支付寶小程式更新程式
• 支付寶小程式開發工具： 下載 ｜ 小程式
• 目前無分包的配置，並且包體積限制在 3M。
• showLoading 是不透傳的，也就是說 loading 顯示的時候無法點選頁面內容。
• 檔名或資料夾名中不允許出現 @ 符號。
• 網路請求返回的資料會嚴格按照 dataType 進行處理，如果不符合規範則會丟擲錯誤，而不是按照原格式返回。
• canvas 元件的標識是 id，而不是 canvas-id。目前還未進行處理，所以需要主動新增 id 屬性。
• 目前測試的結果，導航欄只有設定背景顏色為 #FFF(FFF) 時才會變成黑色文字。
• 支付寶小程式的導航欄是支援透明漸變效果的，後面會提供相關的配置。
• 使用偽元素做邊框時，高度值不能用 1rpx，需要直接用 1px。
• 不支援 ECharts。
• 支付功能模擬不了，需要真機測試。

百度小程式開發注意

• 百度小程式更新日誌
• 百度小程式開發工具： 百度智慧小程式文件
• 不支援屬性選擇器。
• 不支援 scoped。
• login / getUserInfo /支付等功能在模擬器（開發工具）上不能模擬。
• map 元件在開發工具上預覽效果不對，但是手機上是對的。
• getSystemInfo 獲取到的 windowHeight 在模擬器中值不正確，真機預覽是正確的。
• v-if 和 v-for 不可在同一標籤下同時使用。
• 頁面中引入自定義元件時，渲染的結果中外層會有一個 template 標籤，這會導致部分選擇器對應的樣式匹配不上。

各家小程式的瀏覽器核心不同，會造成css相容性問題

查閱細節參考：關於手機webview核心、預設瀏覽器、各家小程式的渲染層瀏覽器的區別和相容性 - DCloud問答

vendor.js過大的處理方式

小程式工具提示vendor.js過大，已經跳過es6向es5轉換。這個轉換問題本身不用理會，因為vendor.js已經是es5的了。

關於體積控制，參考如下：

• 使用執行時程式碼壓縮HBuilderX建立的專案勾選執行-->執行到小程式模擬器-->執行時是否壓縮程式碼cli建立的專案可以在pacakge.json中新增引數--minimize，示例："dev:mp-weixin": "cross-env NODE_ENV=development UNI_PLATFORM=mp-weixin vue-cli-service uni-build --watch --minimize"
• 使用分包最佳化，關於分包最佳化的說明