跨端原理与适配策略

What — 是什么

跨端开发是指使用一套代码/技术栈同时覆盖多个平台（Web、iOS、Android、小程序、桌面等）的开发模式。核心思路是通过抽象层抹平平台差异，让开发者关注业务逻辑而非平台特性。根据抽象层的位置和方式不同，主要分为四大流派：WebView 嵌套、原生映射、自绘引擎、编译转换。

四大跨端流派：

┌───────────────────────────────────────────────────────────┐
│                    跨端开发四大流派                         │
├─────────────────┬─────────────────────────────────────────┤
│                 │           抽象层位置                      │
│                 ├──────────────┬──────────────────────────┤
│                 │   渲染层     │        逻辑层             │
├─────────────────┼──────────────┼──────────────────────────┤
│ 使用平台渲染引擎 │ ① WebView   │ ② 原生组件映射            │
│                 │  嵌套渲染    │  (React Native/Weex)      │
├─────────────────┼──────────────┼──────────────────────────┤
│ 自带渲染引擎    │ ③ 自绘引擎   │ ④ 编译转换                │
│                 │  (Flutter)   │  (Taro/uni-app/Kotlin MP) │
└─────────────────┴──────────────┴──────────────────────────┘

流派一：WebView 嵌套渲染

┌────────────────────────────┐
│     原生 Shell（导航栏）    │
├────────────────────────────┤
│        WebView 容器        │
│  ┌──────────────────────┐  │
│  │   HTML/CSS/JS        │  │
│  │   (Web 应用)         │  │
│  └──────────────────────┘  │
│  JSBridge ←→ 原生 API     │
├────────────────────────────┤
│    平台 API（相机/推送等）  │
└────────────────────────────┘

• 原理：在原生 App 中嵌入 WebView 加载 Web 页面，通过 JSBridge 调用原生能力
• 代表：Capacitor、Cordova、微信小程序 WebView 页面、Hybrid App
• 优点：Web 技术零学习成本、开发效率高、热更新方便
• 缺点：性能受 WebView 限制、复杂交互卡顿、原生体验不足

流派二：原生组件映射

┌────────────────────────────────────┐
│        JS Runtime (JSC/Hermes)     │
│  React/Vue 组件 → Virtual DOM      │
│  Reconciler diff → 更新指令        │
├────────────────────────────────────┤
│           Bridge / JSI              │
│    JS ↔ 原生通信（异步/同步）      │
├────────────────────────────────────┤
│  iOS: UIView    │  Android: View   │
│  原生组件树     │  原生组件树       │
└────────────────────────────────────┘

• 原理：JS 中编写声明式 UI，框架将虚拟 DOM 映射到平台原生组件
• 代表：React Native（新架构 Fabric + JSI）、Weex（已停维）
• 优点：接近原生性能、原生组件体验好、可混合原生开发
• 缺点：Bridge 通信有开销（旧架构）、需要理解原生概念、调试复杂

流派三：自绘引擎

┌────────────────────────────────────┐
│      Dart/JS Runtime               │
│      Widget/Component Tree          │
├────────────────────────────────────┤
│      自绘渲染引擎 (Skia/Impeller)   │
│      直接调用 GPU 绘制像素          │
├────────────────────────────────────┤
│  iOS: Metal    │  Android: Vulkan   │
│  macOS: Metal  │  Windows: Angle    │
│  Linux: EGL    │  Web: CanvasKit    │
└────────────────────────────────────┘

• 原理：自带渲染引擎，不依赖平台 UI 组件，直接在 Canvas 上绘制
• 代表：Flutter（Skia/Impeller）
• 优点：像素级一致性、60fps 流畅、不受平台 UI 限制
• 缺点：包体积大（含引擎）、非原生观感、需学习新语言/框架

流派四：编译转换

┌────────────────────────────────────┐
│   源码（React/Vue 语法）            │
├────────────────────────────────────┤
│        编译器 / 运行时              │
│  ┌────────────┬──────────────────┐ │
│  │ 编译时转换  │ 运行时模拟DOM    │ │
│  │ (uni-app)  │ (Taro 3+/Remax) │ │
│  └─────┬──────┴────────┬─────────┘ │
│        ↓               ↓           │
│  小程序模板        小程序setData    │
├────────────────────────────────────┤
│  微信 │ 支付宝 │ 百度 │ H5 │ ...  │
└────────────────────────────────────┘

• 原理：将 React/Vue 代码编译/转换为目标平台代码
• 代表：Taro（运行时）、uni-app（编译时）、Kotlin Multiplatform（编译时）
• 优点：一套代码多端运行、学习成本低、小程序支持好
• 缺点：平台差异需要条件编译、部分特性受限

跨端方案全景对比：

Why — 为什么

跨端的核心价值：

• 降本增效：一套代码多端运行，开发和维护成本显著降低
• 体验一致性：统一 UI/交互规范，各平台体验一致
• 快速试错：MVP 阶段快速覆盖多端，验证产品方向
• 团队复用：Web 前端团队可直接扩展到移动端/桌面端

各场景选型建议：

跨端的真实代价：

• 性能折衷：没有一种方案能在所有平台都达到原生性能
• 平台适配：每个平台都有独特的坑，条件编译不可避免
• 调试困难：跨端 Bug 定位比单端更复杂
• 升级风险：框架升级可能引入跨端回归
• 生态限制：部分原生 SDK 没有跨端封装，需要写原生插件

How — 怎么用

JSBridge 通信原理

JSBridge 是 WebView 方案的核心，实现 JS 与原生之间的双向通信。

JS → 原生：

// 方式1：URL Scheme 拦截（通用但低效）
function callNativeBySchema(method: string, params: any) {
  const url = `jsbridge://${method}?params=${encodeURIComponent(JSON.stringify(params))}`;
  // iOS: window.location.href = url;  或 iframe.src = url
  // Android: window.prompt(url) 被 WebView.onJsPrompt 拦截
  const iframe = document.createElement('iframe');
  iframe.style.display = 'none';
  iframe.src = url;
  document.body.appendChild(iframe);
  setTimeout(() => document.body.removeChild(iframe), 0);
}

// 方式2：注入全局对象（推荐，高效）
// 原生端注入：WKWebView.evaluateJavascript("window.NativeBridge = ...")
// Android: WebView.addJavascriptInterface
declare global {
  interface Window {
    NativeBridge: {
      call: (method: string, params: string, callbackId: string) => void;
    };
  }
}

let callbackId = 0;
const callbacks: Record<string, Function> = {};

function callNative(method: string, params: any): Promise<any> {
  return new Promise((resolve) => {
    const id = `cb_${++callbackId}`;
    callbacks[id] = resolve;
    window.NativeBridge.call(method, JSON.stringify(params), id);
  });
}

// 原生回调 JS
window.__bridgeCallback = (callbackId: string, result: string) => {
  const callback = callbacks[callbackId];
  if (callback) {
    callback(JSON.parse(result));
    delete callbacks[callbackId];
  }
};

原生 → JS：

// iOS (WKWebView)
// [webView evaluateJavaScript:@"callbackFunction('data')" completionHandler:nil]

// Android (WebView)
// webView.evaluateJavascript("callbackFunction('data')", null)

// 封装事件系统
type EventCallback = (data: any) => void;

class BridgeEventEmitter {
  private events: Record<string, EventCallback[]> = {};

  on(event: string, callback: EventCallback) {
    if (!this.events[event]) this.events[event] = [];
    this.events[event].push(callback);
  }

  off(event: string, callback?: EventCallback) {
    if (!callback) { delete this.events[event]; return; }
    this.events[event] = this.events[event]?.filter(cb => cb !== callback) || [];
  }

  emit(event: string, data: any) {
    this.events[event]?.forEach(cb => cb(data));
  }
}

// 原生调用此方法触发 JS 事件
window.__dispatchBridgeEvent = (event: string, data: string) => {
  bridgeEmitter.emit(event, JSON.parse(data));
};

平台差异统一处理

环境检测：

// utils/platform.ts
const ua = navigator.userAgent;

export const platform = {
  isWechat: /MicroMessenger/i.test(ua),
  isAlipay: /AlipayClient/i.test(ua),
  isBytedance: /ToutiaoMicroApp/i.test(ua),
  isMiniProgram: window.__wxjs_environment === 'miniprogram',
  isIOS: /iPhone|iPad|iPod/i.test(ua),
  isAndroid: /Android/i.test(ua),
  isIPhoneX: /iPhone/i.test(ua) && window.screen.height >= 812,
  isPWA: window.matchMedia('(display-mode: standalone)').matches,
  isElectron: ua.includes('Electron'),
  isTauri: !!(window as any).__TAURI__,
};

// 跨端 API 适配器
export function adaptStorage() {
  // 小程序
  if (platform.isMiniProgram) {
    return {
      get: (key: string) => wx.getStorageSync(key),
      set: (key: string, value: any) => wx.setStorageSync(key, value),
      remove: (key: string) => wx.removeStorageSync(key),
    };
  }
  // Web / WebView
  return {
    get: (key: string) => {
      const val = localStorage.getItem(key);
      return val ? JSON.parse(val) : null;
    },
    set: (key: string, value: any) => localStorage.setItem(key, JSON.stringify(value)),
    remove: (key: string) => localStorage.removeItem(key),
  };
}

export function adaptNavigation() {
  // 小程序
  if (platform.isMiniProgram) {
    return {
      push: (url: string) => wx.navigateTo({ url }),
      replace: (url: string) => wx.redirectTo({ url }),
      back: () => wx.navigateBack(),
    };
  }
  // Web
  return {
    push: (url: string) => window.history.pushState(null, '', url),
    replace: (url: string) => window.history.replaceState(null, '', url),
    back: () => window.history.back(),
  };
}

条件编译统一封装：

// utils/conditional.ts
type Platform = 'weapp' | 'alipay' | 'h5' | 'rn' | 'electron' | 'tauri';

function getPlatform(): Platform {
  if (typeof wx !== 'undefined') return 'weapp';
  if (typeof my !== 'undefined') return 'alipay';
  if (platform.isElectron) return 'electron';
  if (platform.isTauri) return 'tauri';
  return 'h5';
}

// 平台条件执行
export function runOnPlatform<T>(
  platformMap: Partial<Record<Platform, () => T>>,
  fallback?: () => T
): T | undefined {
  const current = getPlatform();
  const fn = platformMap[current] || fallback;
  return fn?.();
}

// 使用示例
const image = runOnPlatform({
  weapp: () => wx.chooseImage({ count: 1 }),
  h5: () => { /* input[type=file] */ },
  electron: () => { /* Electron dialog */ },
  tauri: () => { /* Tauri dialog */ },
}, () => { /* 默认降级 */ });

响应式适配方案

尺寸适配：

// utils/responsive.ts
const DESIGN_WIDTH = 375; // 设计稿宽度

// rem 适配方案
export function initRemAdapter(designWidth = DESIGN_WIDTH) {
  const docEl = document.documentElement;
  const resizeEvt = 'orientationchange' in window ? 'orientationchange' : 'resize';

  function recalc() {
    const clientWidth = docEl.clientWidth;
    if (!clientWidth) return;
    docEl.style.fontSize = `${(clientWidth / designWidth) * 100}px`;
  }

  recalc();
  window.addEventListener(resizeEvt, recalc);
  document.addEventListener('DOMContentLoaded', recalc);
}

// 使用时：设计稿 375px 下 1rem = 100px
// 元素宽度 200px → 2rem

// vw 适配方案（推荐，无需 JS）
// postcss-px-to-viewport 自动转换
// postcss.config.js:
// {
//   plugins: {
//     'postcss-px-to-viewport': {
//       viewportWidth: 375,
//       unitPrecision: 5,
//       viewportUnit: 'vw',
//       selectorBlackList: [],
//       minPixelValue: 1,
//       mediaQuery: false,
//     }
//   }
// }

安全区域适配：

/* 通用安全区域方案 */
.safe-area-top {
  padding-top: constant(safe-area-inset-top);    /* iOS 11.0 */
  padding-top: env(safe-area-inset-top);          /* iOS 11.2+ */
}

.safe-area-bottom {
  padding-bottom: constant(safe-area-inset-bottom);
  padding-bottom: env(safe-area-inset-bottom);
}

/* 全面屏底部固定栏 */
.bottom-bar {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  padding-bottom: constant(safe-area-inset-bottom);
  padding-bottom: env(safe-area-inset-bottom);
  background: #fff;
}

/* 横屏安全区域 */
@media (orientation: landscape) {
  .safe-area-landscape {
    padding-left: env(safe-area-inset-left);
    padding-right: env(safe-area-inset-right);
  }
}

<!-- viewport 设置 -->
<meta
  name="viewport"
  content="width=device-width, initial-scale=1.0, viewport-fit=cover"
>

跨端样式适配

CSS 兼容性处理：

/* 1. 使用 Autoprefixer 自动添加前缀 */
/* postcss.config.js 配置即可，无需手动写 */

/* 2. 常见兼容性写法 */
.flex-center {
  display: -webkit-box;
  display: -webkit-flex;
  display: flex;
  -webkit-box-pack: center;
  -webkit-justify-content: center;
  justify-content: center;
  -webkit-box-align: center;
  -webkit-align-items: center;
  align-items: center;
}

/* 3. 1px 边框问题（高清屏） */
.hairline-border {
  position: relative;
}
.hairline-border::after {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  width: 200%;
  height: 200%;
  border: 1px solid #ddd;
  transform: scale(0.5);
  transform-origin: 0 0;
  pointer-events: none;
}

/* 4. 点击高亮去除（移动端） */
.no-tap-highlight {
  -webkit-tap-highlight-color: transparent;
  -webkit-touch-callout: none;
  user-select: none;
}

/* 5. 滚动优化 */
.smooth-scroll {
  -webkit-overflow-scrolling: touch;
  overscroll-behavior: contain;
}

/* 6. 文字截断 */
.ellipsis {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}
.ellipsis-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

跨端样式策略：

// 样式适配器：不同平台使用不同单位
// postcss.config.js
module.exports = {
  plugins: {
    // 小程序用 rpx
    'postcss-pxtounit': {
      targetUnit: process.env.TARO_ENV === 'weapp' ? 'rpx' : 'px',
      unitPrecision: 5,
      propList: ['*'],
    },
    // H5 用 vw
    'postcss-px-to-viewport': process.env.TARO_ENV === 'h5' ? {
      viewportWidth: 375,
      unitPrecision: 5,
      viewportUnit: 'vw',
    } : false,
    // Electron 不做转换
  },
};

跨端组件抽象

// components/CrossPlatformImage/index.tsx
import { platform } from '@/utils/platform';

interface ImageProps {
  src: string;
  width?: number;
  height?: number;
  mode?: 'aspectFill' | 'aspectFit' | 'widthFix';
  lazyLoad?: boolean;
  onClick?: () => void;
}

// 根据平台返回不同实现
function CrossPlatformImage({ src, width, height, mode = 'aspectFill', lazyLoad, onClick }: ImageProps) {
  // 小程序
  if (platform.isMiniProgram) {
    return (
      <image
        src={src}
        style={{ width: `${width}rpx`, height: `${height}rpx` }}
        mode={mode}
        lazy-load={lazyLoad}
        onClick={onClick}
      />
    );
  }

  // React Native
  if (platform.isRN) {
    return (
      <RNImage
        source={{ uri: src }}
        style={{ width, height, resizeMode: mode === 'aspectFill' ? 'cover' : 'contain' }}
      />
    );
  }

  // Web / Electron
  const objectFit = mode === 'aspectFill' ? 'cover' : mode === 'aspectFit' ? 'contain' : 'fill';
  return (
    <img
      src={src}
      style={{ width, height, objectFit }}
      loading={lazyLoad ? 'lazy' : 'eager'}
      onClick={onClick}
    />
  );
}

列表组件抽象：

// components/CrossPlatformList/index.tsx
interface ListProps<T> {
  data: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  onEndReached?: () => void;
  onPullRefresh?: () => Promise<void>;
  keyExtractor: (item: T) => string;
  estimatedItemSize?: number;
}

function CrossPlatformList<T>({
  data, renderItem, onEndReached, onPullRefresh, keyExtractor, estimatedItemSize = 80
}: ListProps<T>) {
  // 小程序：使用 scroll-view + 触底事件
  if (platform.isMiniProgram) {
    return (
      <scroll-view
        scrollY
        refresherEnabled={!!onPullRefresh}
        onRefresherRefresh={onPullRefresh}
        onScrollToLower={onEndReached}
      >
        {data.map((item, i) => (
          <view key={keyExtractor(item)}>{renderItem(item, i)}</view>
        ))}
      </scroll-view>
    );
  }

  // Web：使用虚拟滚动
  return (
    <VirtualList
      data={data}
      itemSize={estimatedItemSize}
      renderItem={renderItem}
      onEndReached={onEndReached}
    />
  );
}

跨端网络层适配

// services/http/cross-platform.ts
import { platform } from '@/utils/platform';

interface RequestConfig {
  url: string;
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
  data?: any;
  header?: Record<string, string>;
}

interface Response<T> {
  data: T;
  statusCode: number;
  header: Record<string, string>;
}

async function crossPlatformRequest<T>(config: RequestConfig): Promise<Response<T>> {
  // 小程序
  if (platform.isWechat) {
    return new Promise((resolve, reject) => {
      wx.request({
        url: config.url,
        method: config.method,
        data: config.data,
        header: config.header,
        success: (res) => resolve({
          data: res.data as T,
          statusCode: res.statusCode,
          header: res.header as Record<string, string>,
        }),
        fail: reject,
      });
    });
  }

  // 支付宝小程序
  if (platform.isAlipay) {
    return new Promise((resolve, reject) => {
      my.request({
        url: config.url,
        method: config.method,
        data: config.data,
        headers: config.header,
        success: (res) => resolve({
          data: res.data as T,
          statusCode: res.status,
          header: res.headers as Record<string, string>,
        }),
        fail: reject,
      });
    });
  }

  // Electron / Tauri / Web
  const response = await fetch(config.url, {
    method: config.method,
    body: config.data ? JSON.stringify(config.data) : undefined,
    headers: {
      'Content-Type': 'application/json',
      ...config.header,
    },
  });

  return {
    data: await response.json() as T,
    statusCode: response.status,
    header: Object.fromEntries(response.headers.entries()),
  };
}

跨端存储适配

// services/storage/cross-platform.ts
import { platform } from '@/utils/platform';

export interface IStorage {
  get<T = any>(key: string): Promise<T | null>;
  set<T = any>(key: string, value: T): Promise<void>;
  remove(key: string): Promise<void>;
  clear(): Promise<void>;
  keys(): Promise<string[]>;
}

// Web localStorage
class WebStorage implements IStorage {
  async get<T>(key: string): Promise<T | null> {
    const val = localStorage.getItem(key);
    return val ? JSON.parse(val) : null;
  }
  async set<T>(key: string, value: T): Promise<void> {
    localStorage.setItem(key, JSON.stringify(value));
  }
  async remove(key: string): Promise<void> { localStorage.removeItem(key); }
  async clear(): Promise<void> { localStorage.clear(); }
  async keys(): Promise<string[]> {
    return Object.keys(localStorage);
  }
}

// IndexedDB（大容量）
class IndexedDBStorage implements IStorage {
  private db: IDBDatabase | null = null;

  async init(dbName = 'app_storage', storeName = 'keyvalue') {
    return new Promise<void>((resolve, reject) => {
      const request = indexedDB.open(dbName, 1);
      request.onupgradeneeded = () => {
        request.result.createObjectStore(storeName);
      };
      request.onsuccess = () => { this.db = request.result; resolve(); };
      request.onerror = () => reject(request.error);
    });
  }

  private getStore(mode: IDBTransactionMode = 'readonly') {
    const tx = this.db!.transaction('keyvalue', mode);
    return tx.objectStore('keyvalue');
  }

  async get<T>(key: string): Promise<T | null> {
    return new Promise((resolve, reject) => {
      const req = this.getStore().get(key);
      req.onsuccess = () => resolve(req.result || null);
      req.onerror = () => reject(req.error);
    });
  }

  async set<T>(key: string, value: T): Promise<void> {
    return new Promise((resolve, reject) => {
      const req = this.getStore('readwrite').put(value, key);
      req.onsuccess = () => resolve();
      req.onerror = () => reject(req.error);
    });
  }

  async remove(key: string): Promise<void> {
    return new Promise((resolve, reject) => {
      const req = this.getStore('readwrite').delete(key);
      req.onsuccess = () => resolve();
      req.onerror = () => reject(req.error);
    });
  }

  async clear(): Promise<void> {
    return new Promise((resolve, reject) => {
      const req = this.getStore('readwrite').clear();
      req.onsuccess = () => resolve();
      req.onerror = () => reject(req.error);
    });
  }

  async keys(): Promise<string[]> {
    return new Promise((resolve, reject) => {
      const req = this.getStore().getAllKeys();
      req.onsuccess = () => resolve(req.result as string[]);
      req.onerror = () => reject(req.error);
    });
  }
}

// 工厂函数
export function createStorage(): IStorage {
  if (platform.isMiniProgram) {
    // 小程序用 Storage API（已在各框架的 API 中封装）
    return new WebStorage(); // Taro/uni-app 已做适配
  }
  // 优先使用 IndexedDB（大容量，5MB+）
  if (typeof indexedDB !== 'undefined') {
    const storage = new IndexedDBStorage();
    storage.init();
    return storage;
  }
  return new WebStorage();
}

跨端路由适配

// router/cross-platform.ts
import { platform } from '@/utils/platform';

interface RouteConfig {
  path: string;
  params?: Record<string, string>;
}

class CrossPlatformRouter {
  navigateTo(route: RouteConfig) {
    const url = this.buildUrl(route);

    if (platform.isWechat) {
      wx.navigateTo({ url });
    } else if (platform.isAlipay) {
      my.navigateTo({ url });
    } else {
      // Web 使用 history API 或框架路由
      window.history.pushState(null, '', url);
    }
  }

  redirectTo(route: RouteConfig) {
    const url = this.buildUrl(route);

    if (platform.isWechat) {
      wx.redirectTo({ url });
    } else if (platform.isAlipay) {
      my.redirectTo({ url });
    } else {
      window.history.replaceState(null, '', url);
    }
  }

  goBack(delta = 1) {
    if (platform.isWechat) {
      wx.navigateBack({ delta });
    } else if (platform.isAlipay) {
      my.navigateBack({ delta });
    } else {
      window.history.go(-delta);
    }
  }

  switchTab(path: string) {
    if (platform.isWechat) {
      wx.switchTab({ url: path });
    } else if (platform.isAlipay) {
      my.switchTab({ url: path });
    } else {
      window.location.href = path;
    }
  }

  private buildUrl(route: RouteConfig): string {
    if (!route.params) return route.path;
    const query = new URLSearchParams(route.params).toString();
    return `${route.path}?${query}`;
  }
}

export const router = new CrossPlatformRouter();

跨端性能优化策略

首屏优化（通用）：

渲染优化（WebView 方案）：

// 1. 减少重排重绘
// 差：频繁修改 DOM
element.style.width = '100px';
element.style.height = '200px';
element.style.margin = '10px';

// 好：一次性修改
element.style.cssText = 'width:100px;height:200px;margin:10px';

// 好：使用 class 切换
element.className = 'active';

// 2. 批量 DOM 操作
// 差：逐个插入
data.forEach(item => {
  list.appendChild(createElement(item)); // 每次触发重排
});

// 好：DocumentFragment
const fragment = document.createDocumentFragment();
data.forEach(item => {
  fragment.appendChild(createElement(item));
});
list.appendChild(fragment); // 只触发一次重排

// 3. 虚拟滚动
// 只渲染可视区域，长列表 10000+ 项也能流畅
import { VirtualList } from 'react-window';

function LongList({ items }) {
  return (
    <VirtualList
      height={600}
      itemCount={items.length}
      itemSize={50}
      width='100%'
    >
      {({ index, style }) => (
        <div style={style}>{items[index].name}</div>
      )}
    </VirtualList>
  );
}

// 4. 节流与防抖
function throttle(fn: Function, delay: number) {
  let timer: number | null = null;
  return function (this: any, ...args: any[]) {
    if (timer) return;
    timer = setTimeout(() => { fn.apply(this, args); timer = null; }, delay);
  };
}

// 滚动事件节流
window.addEventListener('scroll', throttle(handleScroll, 100));

setData 优化（小程序方案）：

// 1. 减少 setData 频率
// 差：每次更新都 setData
list.forEach(item => {
  item.status = 'updated';
  this.setData({ list }); // N 次 setData
});

// 好：合并更新
const updatedList = list.map(item => ({ ...item, status: 'updated' }));
this.setData({ list: updatedList }); // 1 次 setData

// 2. 只传变化的数据
// 差：全量更新
this.setData({ user: newFullUserObject });

// 好：路径更新
this.setData({ 'user.name': '新名字', 'user.age': 25 });

// 3. 避免 setData 传递大对象
// 差：图片 base64
this.setData({ imageData: veryLongBase64String }); // 数 MB

// 好：只传 URL
this.setData({ imageUrl: 'https://cdn.example.com/img.jpg' });

// 4. 后台页面不 setData
// 页面 onHide 后，延迟到 onShow 时再更新

跨端测试策略

// 跨端测试需要关注：各平台 API 差异、UI 渲染差异、原生能力可用性

// 1. 平台适配层单元测试
import { describe, it, expect, vi } from 'vitest';

describe('crossPlatformRequest', () => {
  it('should call wx.request on WeChat', async () => {
    global.wx = { request: vi.fn() };
    await crossPlatformRequest({ url: '/api/test', method: 'GET' });
    expect(global.wx.request).toHaveBeenCalled();
  });

  it('should call fetch on Web', async () => {
    global.fetch = vi.fn().mockResolvedValue({
      json: () => Promise.resolve({ data: 'test' }),
      status: 200,
      headers: new Headers(),
    });
    await crossPlatformRequest({ url: '/api/test', method: 'GET' });
    expect(global.fetch).toHaveBeenCalled();
  });
});

// 2. 组件渲染测试
// 使用 @testing-library/react 测试组件逻辑
// UI 差异在各平台真机测试

// 3. E2E 测试
// 微信小程序：miniprogram-automator
// H5：Playwright / Cypress
// App：Appium / Detox

// 4. 兼容性矩阵
// 在 CI 中配置多平台测试
const testMatrix = {
  platforms: ['weapp', 'alipay', 'h5'],
  devices: ['iPhone 13', 'Pixel 7', 'iPad'],
  versions: ['iOS 15', 'iOS 16', 'Android 12', 'Android 13'],
};

跨端项目工程化

# .github/workflows/cross-platform-ci.yml
name: Cross Platform CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

  build-weapp:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build:weapp
      - uses: actions/upload-artifact@v4
        with:
          name: weapp-dist
          path: dist/weapp

  build-h5:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build:h5
      - uses: actions/upload-artifact@v4
        with:
          name: h5-dist
          path: dist/h5

  build-android:
    needs: test
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build:android

常见问题与踩坑

最佳实践

• 选择跨端方案前，明确目标平台和性能要求，不做”全都要”的方案
• 优先使用各方案自带的跨端 API，而非自己封装（Taro.xxx / uni.xxx / Capacitor.xxx）
• 样式使用 rpx/vw/rem 等响应式单位，避免 px 硬编码
• 抽象平台差异到适配层，业务代码不直接调用平台 API
• 跨端组件遵循”核心逻辑统一，渲染层分离”原则
• 条件编译/运行时判断用于处理真正的平台差异，不要过度使用
• 图片统一走 CDN，按设备 DPR 返回对应分辨率
• 首屏性能：骨架屏 + 代码分割 + 预加载 + 缓存策略
• 建立兼容性矩阵，覆盖主流设备和系统版本
• 跨端测试优先保证核心流程在各平台功能正确，UI 差异靠真机验收

面试题

Q1: 跨端开发的四大流派分别是什么？各自的优缺点？

① WebView 嵌套（Capacitor/Cordova）：Web 技术零学习成本，但性能受 WebView 限制；② 原生组件映射（React Native/Weex）：接近原生性能和体验，但需理解原生概念，Bridge 通信有开销；③ 自绘引擎（Flutter）：像素级一致、60fps 流畅，但包体积大、非原生观感、需学 Dart；④ 编译转换（Taro/uni-app）：一套代码多端小程序，但平台差异需条件编译，运行时方案有额外开销。选型关键看目标平台（小程序→编译转换，App→原生映射/自绘，快速上线→WebView）。

Q2: JSBridge 的通信原理是什么？有哪些方式？

JSBridge 实现 JS 与原生双向通信。JS→原生：① URL Scheme 拦截（iframe.src 改变，原生 shouldOverrideUrlLoading 拦截）；② prompt 拦截（window.prompt 触发 onJsPrompt）；③ 注入全局对象（WKWebView evaluateJavascript 注入 window.NativeBridge，Android addJavascriptInterface）— 推荐，性能最好。原生→JS：① evaluateJavascript 直接执行 JS 代码。通信流程：JS 调用 → 传参+callbackId → 原生处理 → 通过 evaluateJavascript 回调 callback → JS 执行回调。

Q3: React Native 的新架构（Fabric + JSI + TurboModules）解决了什么问题？

旧架构 Bridge 的三大问题：① 异步通信：JS 与原生之间只能异步 JSON 序列化，大量数据传输卡顿；② 全量加载：所有 Native Module 启动时全量加载，影响启动速度；③ 不可中断渲染：无法优先级调度，滚动时可能卡顿。新架构：JSI 实现 JS 直接持有 C++ 对象引用，同步调用无需序列化；Fabric 渲染系统支持同步布局和优先级调度（滚动优先于数据加载）；TurboModules 按需加载原生模块，减少启动时间；Codegen 根据 TS 规范自动生成类型安全的胶水代码。

Q4: Flutter 为什么选择自绘而不是使用原生组件？

选择自绘的原因：① 像素一致性：自绘引擎在所有平台渲染结果完全一致，不受系统版本/厂商定制影响；② 灵活性：不受原生组件 API 限制，可以实现任意 UI 效果（如弹性动画、自定义滑动）；③ 性能控制：直接调用 GPU（Skia/Impeller），不经过平台 UI 框架，减少中间层开销；④ 跨平台简单：只需适配一个渲染引擎，而非每个平台的原生组件体系。代价：包体积大（含 Skia ~4MB）、非原生观感（Material/Cupertino 是模拟的）、输入法和辅助功能适配不完善。

Q5: 跨端项目如何做性能优化？

分三个层面：① 首屏优化：代码分割（路由懒加载）、预加载关键资源、骨架屏、SSR（H5）、缓存策略；② 渲染优化：虚拟滚动（长列表）、减少 DOM 节点、CSS 动画用 transform/opacity 触发 GPU 合成、避免频繁 setState/setData；③ 通信优化：合并 setData 减少频率、只传变化数据、避免大对象传输、使用 JSI/JSI 替代异步 Bridge。关键指标：首屏 FCP < 1.5s、列表滚动 FPS > 55、setData 单次 < 10ms。

Q6: 如何在跨端项目中处理平台差异？

三个层级：① API 层：封装跨端适配器，业务代码只调用统一接口，适配器内部根据平台分发（如 crossPlatformRequest 封装 wx.request/fetch）；② 组件层：抽象跨端组件，各平台分别实现渲染逻辑，对外暴露统一 props；③ 编译层：使用条件编译（Taro #ifdef、uni-app #ifdef）或 process.env.TARO_ENV 运行时判断。原则：平台差异收敛到适配层，业务代码不感知平台；能用运行时判断就不用条件编译（更灵活）；条件编译只用于 API 真正不存在的场景。

Q7: 小程序的 setData 为什么慢？如何优化？

setData 慢的原因：① 通信开销：逻辑层（JSCore）→ 原生层 → 视图层（WebView），两次跨线程通信；② 序列化：数据需要 JSON 序列化/反序列化；③ 全量 diff：视图层收到数据后需要 diff 整个虚拟 DOM 树。优化：① 减少 setData 频率：合并多次更新为一次；② 只传变化数据：用路径更新 'list[0].name': '新值' 而非整个 list；③ 避免大对象：不传 base64 图片等大数据；④ 拆分组件：每个组件独立 setData，减少数据量；⑤ 后台页面不更新：onHide 时暂停 setData，onShow 时恢复。

Q8: Taro 和 uni-app 的架构差异导致的技术选择影响是什么？

核心架构差异：Taro 3+ 是运行时方案（在小程序逻辑层模拟 DOM，React/Vue 直接运行），uni-app 是编译时方案（将 Vue 模板编译为小程序 WXML）。影响：① 包体积：Taro 含 runtime ~50KB，uni-app 更小；② 语法支持：Taro 支持完整 JSX/VNode（高阶组件、动态渲染），uni-app 受限于模板编译（v-if/v-for 可以，但复杂 JS 表达式受限）；③ 性能：简单页面两者接近，复杂交互 Taro 的 runtime 开销更明显（频繁 setData）；④ 调试：Taro 可用 React DevTools，uni-app 调试更接近原生小程序。选择：需要 React 生态或复杂 JSX → Taro；追求轻量和性能 → uni-app。

相关链接：

• uni-app跨端开发
• Taro跨端框架
• Capacitor跨端开发
• React Native移动开发
• Electron桌面开发
• Tauri桌面开发
• Flutter核心与Widget体系
• 响应式设计
• 移动端适配方案