你的 uni-app 項目在 H5 和 App 端跑得流暢，一編譯成微信小程序進行真機調試，直接白屏，或頁面元素莫名消失，而控制臺只給出一條語焉不詳?shù)?Component is not found。這不是個例。uni-app 的跨端一致性建立在條件編譯之上，但條件編譯本身會放大平臺差異——尤其當你的代碼結構開始依賴組件化與分包時，隱性坑會從樣式、生命周期、API 調用、資源路徑四個方向同時暴露。

條件編譯的真實邊界

#ifdef、#ifndef 不是簡單的文本替換。uni-app 編譯器在構建各平臺產(chǎn)物時，會按平臺宏移除不匹配的代碼塊，但不同區(qū)塊的移除邏輯并不一致：

• template 區(qū)塊：直接刪除節(jié)點，可能影響 v-if、v-for 的索引與條件鏈。
• script 區(qū)塊：刪除代碼行，但若跨越塊級作用域，會導致括號錯配或變量未定義。
• style 區(qū)塊：刪除整個選擇器塊，但小程序端對選擇器的限制不會因為條件編譯而自動對齊。

這意味著，只在 script 中做條件編譯遠不夠——你需要對三類區(qū)塊建立統(tǒng)一的平臺隔離策略。

四個高頻陷阱與修正方案

1. 樣式穿透與選擇器限制

小程序使用 Shadow DOM 變體，組件樣式默認隔離，且不支持 >>>、/deep/ 這類 Vue 單文件組件中的穿透寫法。你在 H5 端通過條件編譯直接寫入的穿透樣式：

/* #ifdef H5 */
.parent >>> .child {
  color: red;
}
/* #endif */

在小程序端會被整塊移除，但問題在于，你需要小程序端的替代方案—— externalClasses 或自定義 style 屬性透傳——卻常常忘記在條件編譯外提供 fallback。正確做法是把小程序適配方案放在 #ifdef MP-WEIXIN 內，并為其他平臺保留穿透寫法：

/* #ifdef MP-WEIXIN */
/* 使用 externalClasses 配合組件定義 */
/* #endif */
/* #ifndef MP-WEIXIN */
.parent :deep(.child) {
  color: red;
}
/* #endif */

同時，在組件 defineProps 或 options 中聲明 externalClasses: ['custom-class']，并在模板中綁定。只做一半的條件編譯，是小程序樣式翻車的頭號原因。

2. 組件生命周期的時序差

uni-app 為對齊微信小程序原生組件，提供了 pageLifetimes、lifetimes 等生命周期。但在條件編譯的分支中，如果你在 App 端使用了 Vue 標準生命周期（如 mounted）獲取頁面參數(shù)，而在小程序端沒有使用 attached 或 onLoad 的等效鉤子，會出現(xiàn)數(shù)據(jù)尚未就緒就已渲染的情況。典型錯誤如下：

export default {
  mounted() {
    // #ifdef MP-WEIXIN
    // 此處在小程序中可能不會在頁面顯示時觸發(fā)
    // #endif
    this.fetchData();
  }
}

修正是在組件或頁面中使用 uni-app 統(tǒng)一的生命周期 onReady（頁面）或 mounted（組件），但針對小程序組件的特殊行為，必須增加 #ifdef MP-WEIXIN 分支內調用 this.$nextTick 或在 ready 生命周期中執(zhí)行依賴 DOM 的操作。更穩(wěn)妥的方案是：將所有平臺公用的初始化邏輯放在 onLoad（頁面）和 created（組件），然后把平臺特有的時序調整代碼放在對應的條件編譯塊中，并用注釋標注原因。

3. API 兼容與分包預加載

uni.request、uni.getSystemInfoSync 等 API 在官方文檔中標為全平臺支持，但參數(shù)選項在兩端存在微妙差異。例如，uni.request 的 responseType 在支付寶小程序中默認行為不同，若你的業(yè)務依賴跨端文件下載，直接使用不帶條件編譯的 uni.downloadFile 會在支付寶端因路徑權限失敗。

更隱蔽的是分包預加載配置 preloadRule。你在 pages.json 中只按微信小程序規(guī)范書寫，當項目編譯到其他小程序平臺時，缺少該配置的其他平臺并不會報錯，而是直接忽略了預加載行為，導致分包頁面首次打開緩慢。必須使用條件編譯拆分 pages.json：

{
  "pages": [...],
  "subPackages": [...],
  // #ifdef MP-WEIXIN
  "preloadRule": {
    "pages/index/index": {
      "network": "all",
      "packages": ["subpackage1"]
    }
  }
  // #endif
}

4. 靜態(tài)資源路徑與權限

小程序包大小限制嚴格，開發(fā)者常將大體積圖片放于 CDN，并在模板中直接使用網(wǎng)絡路徑。但微信小程序要求網(wǎng)絡資源必須配置 downloadFile 合法域名，且在 Skyline 渲染引擎下，未預加載的圖片會反復發(fā)起請求。很多團隊只在 #ifdef H5 內使用 CDN 路徑，而小程序端仍引用本地 static 資源，結果在小程序真機上觸發(fā)“圖片加載失敗”卻遲遲找不到原因。

正確策略：利用 uni-app 提供的 UNI_ASSETS_BASE_URL 編譯時宏，結合條件編譯，為不同平臺輸出不同資源基路徑，并在 manifest.json 中配置好小程序合法域名白名單。示例：

const BASE = process.env.UNI_ASSETS_BASE_URL;
export default {
  data() {
    return {
      logoUrl: BASE + 'logo.png'
    }
  }
}

在小程序端，UNI_ASSETS_BASE_URL 默認為 ./static/，H5 端可配置為 CDN 地址。這樣無需在模板中使用條件編譯，一個變量控制全端適配。

工程化攔截：把問題卡在編譯階段

條件編譯的錯誤通常要到真機調試才會暴露，因為模擬器對樣式隔離、分包加載的模擬不完整。建議從三處建立自動檢查：

1. Git 提交鉤子：在 pre-commit 中執(zhí)行 uni-app 編譯命令，并掃描產(chǎn)物中是否包含特定模式，如小程序產(chǎn)物內仍存在 >>> 選擇器。
2. 條件編譯標記規(guī)范：禁止在 template 中使用大段 #ifdef 包裹多個根節(jié)點，避免節(jié)點移除導致 ref 綁定錯亂。統(tǒng)一規(guī)定“平臺分支文件”模式，將差異較大的組件拆分為 component.wx.vue 和 component.h5.vue，利用 uni-app 自動文件后綴解析。
3. 分平臺構建測試：CI 流水線中至少執(zhí)行微信小程序和支付寶小程序的獨立構建，并運行最少一組 e2e 測試，覆蓋分包跳轉與樣式關鍵頁面。

現(xiàn)在就去檢查你項目中最靠近發(fā)版的三個頁面，搜索是否存在只在 H5 或 App 端有效的樣式穿透寫法、生命周期假設，以及未用條件編譯包裹的分包預加載配置。修正它們，比在用戶手機上排查白屏問題快十倍。