1. 三端同构到底在解决什么问题
第一次听到“三端同构”这个词，很多人脑子里冒出来的第一个疑问是：不就是一套代码跑三个地方吗，有什么好大惊小怪的。但真正在移动端和Web端之间反复横跳过的人会明白，这件事的难度远没有想象中那么简单。所谓三端，通常指的是iOS、Android和Web这三个平台。React Native本身已经解决了iOS和Android的跨端问题，但Web端一直是它的软肋。你写了一个RN项目，产品经理突然说“我们还要一个H5版本”，这时候你面临的选项通常只有两个：要么用React Native Web做适配，要么重新写一套React的Web项目。前者听起来很美，但实际落地时会遇到大量平台差异、样式不兼容、第三方库不支持的问题；后者则意味着双倍的维护成本，每次改需求都要改两遍，时间一长两边逻辑必然分叉。
我之所以花时间研究TS版的三端同构设计，是因为在实际项目里踩过太多“一套代码三端跑”的坑。最早的时候团队尝试过直接用React Native Web，结果发现某些RN的组件在Web上渲染出来的DOM结构完全不是我们想要的，样式对不上设计稿，动画卡顿，路由方案也得重新设计。后来换成Platform.select做条件分支，代码里到处都是Platform.OS === 'web'的判断，维护起来极其痛苦。再后来开始认真思考：三端同构的核心矛盾到底是什么？是API差异吗？是样式系统吗？还是路由和导航？其实归根结底，是抽象层设计的问题。
TypeScript在这个场景里的价值，远不止“类型安全”四个字那么简单。它真正的价值在于，当你试图用一套代码覆盖三个平台时，类型系统能帮你把平台差异显式地暴露出来，而不是让它们在运行时才炸掉。比如你定义了一个跨平台的存储接口，TypeScript会强制你在iOS、Android和Web三个实现里都提供一致的签名，任何一端漏了方法或者参数类型不对，编译阶段就会报错。这比等到测试阶段才发现Web端某个方法没实现要高效得多。
这篇文章适合谁看？如果你正在做或者准备做一个需要同时覆盖移动端和Web端的React Native项目，并且希望用TypeScript来管理复杂度，那这篇内容应该能帮你少走不少弯路。我会从整体架构设计讲到具体的代码实现，包括路由方案、样式适配、平台特定模块的抽象方式，以及我在实际项目中总结出来的一些避坑经验。不会只讲概念，每个环节都会给出可以直接参考的代码结构和配置方式。
2. 整体架构设计与技术选型思路
2.1 为什么选择TypeScript作为同构基础
用TypeScript做三端同构，最直接的好处是接口契约的强制约束。在没有类型系统的项目里，你定义一个跨平台的模块，比如文件存储，iOS端实现了readFile和writeFile，Android端也实现了，但Web端可能因为浏览器限制只实现了readFile，writeFile用了localStorage凑合。这种差异在JavaScript里是隐形的，直到某个平台调用了一个不存在的方法才会暴露。TypeScript的接口定义会强制三端实现完全一致的方法签名，任何缺失都会在编译阶段被拦截。
另一个容易被忽视的好处是重构安全性。三端同构的项目里，一个核心模块的改动可能影响到三个平台的运行结果。比如你把用户认证的token刷新逻辑从回调改成了Promise，如果没有类型系统，你很难快速定位到哪些平台的哪些文件需要同步修改。TypeScript的“查找所有引用”和类型检查能在几秒钟内告诉你影响范围。
还有一个实际考量是团队协作效率。三端同构项目通常需要不同背景的开发者参与，有人擅长RN移动端，有人擅长Web前端。TypeScript的类型定义本身就是一种文档，Web开发者看到PlatformStorage接口的定义，立刻就能明白需要实现哪些方法、参数是什么类型、返回值是什么结构，不需要反复沟通。
2.2 目录结构的分层设计
三端同构项目的目录结构设计，核心原则是共享逻辑与平台实现分离。我试过几种不同的组织方式，最后稳定下来的结构大概是这样的：
src/ common/ # 纯逻辑，不依赖任何平台API utils/ # 工具函数 hooks/ # 通用hooks types/ # 全局类型定义 platform/ # 平台特定实现 storage/ index.ts # 统一导出接口 storage.ios.ts storage.android.ts storage.web.ts navigation/ index.ts navigation.ios.ts navigation.android.ts navigation.web.ts components/ # UI组件 base/ # 基础组件（跨平台） platform/ # 平台特定组件 screens/ # 页面 App.tsx这个结构的关键在于platform目录。每个平台特定的模块都有一个统一的index.ts作为入口，它根据当前运行平台导出对应的实现。React Native的Metro打包器支持.ios.ts、.android.ts、.web.ts这样的文件扩展名自动解析，Web端如果用Webpack或者Vite，也可以通过配置resolve.extensions来实现类似的效果。
注意：Metro默认支持平台扩展名解析，但Web端需要额外配置。如果你用的是Expo，
expo start --web已经内置了处理，但如果是bare RN项目自己搭Web端，需要在打包配置里显式声明扩展名优先级。
2.3 路由方案的统一与差异处理
路由是三端同构里最棘手的问题之一。React Navigation在移动端是事实标准，但它在Web端的表现并不理想，URL同步、浏览器前进后退、SEO这些Web端的基本需求它处理得不够自然。React Router在Web端很成熟，但没法直接用在RN的移动端。
我的方案是抽象一层路由接口，移动端底层用React Navigation，Web端底层用React Router，但上层页面组件通过统一的导航API来跳转。具体来说，定义一个NavigationService接口：
// platform/navigation/index.ts export interface NavigationService { navigate(routeName: string, params?: Record<string, unknown>): void; goBack(): void; getCurrentRoute(): string; reset(routeName: string, params?: Record<string, unknown>): void; }然后iOS和Android端用React Navigation的navigationRef来实现这个接口，Web端用React Router的history对象来实现。页面组件里统一调用NavigationService.navigate('Detail', { id: 123 })，不需要关心底层是哪个路由库。
这样做的好处是，页面组件的代码完全平台无关，路由的具体实现被隔离在platform/navigation目录下。当Web端需要做URL美化或者SEO优化时，只需要改Web端的实现，不会影响到移动端。
2.4 样式系统的跨平台适配策略
样式是另一个重灾区。React Native的StyleSheet和Web的CSS在布局模型上就有本质差异，RN默认是Flexbox布局，但Web的默认布局是块级流。虽然RN Web做了很多适配，但实际项目中还是会遇到各种对不齐的情况。
我的经验是尽量使用RN的StyleSheet API来写样式，因为它在三端都能工作，然后通过一个createStyles工具函数来处理平台差异：
// common/utils/createStyles.ts import { StyleSheet, Platform } from 'react-native'; type Styles = Record<string, any>; export function createStyles<T extends Styles>(styles: T): T { return StyleSheet.create(styles); } export function platformStyles<T extends Styles>( base: T, webOverrides?: Partial<T>, mobileOverrides?: Partial<T> ): T { const platformOverride = Platform.OS === 'web' ? webOverrides : mobileOverrides; return StyleSheet.create({ ...base, ...platformOverride }); }对于确实无法统一的样式，比如Web端需要cursor: pointer而RN不支持，就用Platform.select做条件处理。但我的原则是尽量把平台差异控制在样式文件内部，不要让业务组件里出现大量的平台判断。
3. 核心模块的抽象与实现细节
3.1 存储模块的三端统一接口
存储是最典型的平台差异模块。移动端有AsyncStorage，Web端有localStorage和IndexedDB。三端同构的存储模块需要提供一个统一的异步接口，因为AsyncStorage是异步的，而localStorage是同步的，如果接口设计成同步的，移动端就没法实现。
// platform/storage/index.ts export interface StorageService { getItem(key: string): Promise<string | null>; setItem(key: string, value: string): Promise<void>; removeItem(key: string): Promise<void>; clear(): Promise<void>; multiGet(keys: string[]): Promise<Array<[string, string | null]>>; multiSet(pairs: Array<[string, string]>): Promise<void>; }iOS和Android端的实现直接包装AsyncStorage，Web端用localStorage包装成Promise。这里有一个细节需要注意：localStorage有存储容量限制（通常5MB左右），如果数据量大会抛出QuotaExceededError。我的做法是在Web端实现里加一层降级逻辑，当localStorage写入失败时，自动切换到IndexedDB。虽然IndexedDB的API更复杂，但通过idb-keyval这样的轻量库可以简化操作。
实操心得：Web端的存储实现一定要处理隐私模式下的异常。某些浏览器的隐私模式下localStorage会直接抛出异常，如果不做try-catch，整个应用会白屏。我的做法是在应用启动时先做一次存储可用性检测，不可用就降级到内存存储。
3.2 网络请求层的平台差异处理
网络请求在三端之间的差异相对较小，fetch API在三端都能用。但有几个细节需要处理：移动端的SSL证书验证、Web端的CORS、以及请求超时和重试策略。
我通常会在common目录下封装一个HttpClient，底层用fetch，但加上统一的拦截器、超时控制和错误处理：
// common/utils/httpClient.ts interface RequestConfig { url: string; method?: 'GET' | 'POST' | 'PUT' | 'DELETE'; headers?: Record<string, string>; body?: unknown; timeout?: number; retries?: number; } export async function request<T>(config: RequestConfig): Promise<T> { const { url, method = 'GET', headers = {}, body, timeout = 10000, retries = 2 } = config; const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), timeout); try { const response = await fetch(url, { method, headers: { 'Content-Type': 'application/json', ...headers }, body: body ? JSON.stringify(body) : undefined, signal: controller.signal, }); if (!response.ok) { throw new HttpError(response.status, await response.text()); } return await response.json() as T; } catch (error) { if (retries > 0 && isRetryable(error)) { return request({ ...config, retries: retries - 1 }); } throw error; } finally { clearTimeout(timeoutId); } }Web端需要额外处理CORS问题，这个通常需要后端配合设置响应头。移动端则需要注意Android 9以上默认禁止明文HTTP请求，如果后端接口是HTTP的，需要在AndroidManifest里配置usesCleartextTraffic。
3.3 平台特定组件的优雅降级
有些组件在Web端没有对应的实现，比如DatePickerIOS、Slider这些。我的策略是在Web端提供基于HTML原生元素的替代实现，保持相同的props接口。
以日期选择器为例，移动端用@react-native-community/datetimepicker，Web端用<input type="date" />包装：
// components/platform/DatePicker/index.web.tsx import React from 'react'; interface DatePickerProps { value: Date; onChange: (date: Date) => void; mode?: 'date' | 'time' | 'datetime'; minimumDate?: Date; maximumDate?: Date; } export function DatePicker({ value, onChange, mode = 'date', minimumDate, maximumDate }: DatePickerProps) { const inputType = mode === 'time' ? 'time' : mode === 'datetime' ? 'datetime-local' : 'date'; const formatValue = (date: Date): string => { if (mode === 'time') return date.toTimeString().slice(0, 5); if (mode === 'datetime') return date.toISOString().slice(0, 16); return date.toISOString().slice(0, 10); }; return ( <input type={inputType} value={formatValue(value)} min={minimumDate ? formatValue(minimumDate) : undefined} max={maximumDate ? formatValue(maximumDate) : undefined} onChange={(e) => onChange(new Date(e.target.value))} style={{ padding: 8, borderRadius: 4, border: '1px solid #ccc', width: '100%' }} /> ); }这样页面组件里直接import { DatePicker } from '@/components/platform/DatePicker'，Metro和Webpack会根据平台自动选择正确的实现文件。
3.4 动画系统的跨平台方案
动画是另一个需要仔细处理的领域。React Native的Animated API在Web端通过React Native Web也能工作，但性能不如CSS动画。而Reanimated 2在Web端的支持一直不太稳定。
我的选择是简单动画用Animated API，因为它在三端都能跑，虽然Web端性能不是最优，但对于大多数UI过渡效果足够了。复杂动画用平台特定实现，移动端用Reanimated，Web端用CSS transition或者Framer Motion。
这里有一个判断标准：如果动画只是简单的透明度、位移、缩放变化，Animated API完全够用；如果涉及手势驱动的复杂交互，比如拖拽排序、滑动删除，那就需要分平台实现。分平台实现的成本不低，所以我在项目初期会尽量把动画需求控制在Animated API能覆盖的范围内。
4. 构建配置与打包优化实战
4.1 Metro与Webpack的双构建体系
三端同构项目通常需要两套构建体系：移动端用Metro，Web端用Webpack或Vite。这两套体系的配置需要保持一致的模块解析规则，特别是平台扩展名的处理。
Metro的配置相对简单，默认就支持.ios.ts、.android.ts、.web.ts的解析。Web端的Webpack配置需要显式声明：
// webpack.config.js module.exports = { resolve: { extensions: [ '.web.tsx', '.web.ts', '.web.jsx', '.web.js', '.tsx', '.ts', '.jsx', '.js', ], alias: { 'react-native$': 'react-native-web', }, }, module: { rules: [ { test: /\.(ts|tsx)$/, use: 'babel-loader', exclude: /node_modules/, }, ], }, };关键点是extensions数组的顺序，.web.tsx必须排在.tsx前面，这样Web端打包时会优先选择Web特定实现。alias把react-native映射到react-native-web，让RN的组件在Web端能正常渲染。
注意：如果项目里用了某些不兼容React Native Web的第三方库，需要在Webpack配置里做alias替换或者用
null-loader忽略。我遇到过某个图表库在Web端报错，最后是通过alias替换成Web版本的库解决的。
4.2 TypeScript配置的平台类型隔离
TypeScript的配置需要处理一个特殊问题：移动端和Web端的全局类型定义不同。比如移动端有__DEV__全局变量，Web端有window和document。如果tsconfig里同时包含了这两套类型，编译时不会报错，但代码提示会混乱。
我的做法是用多个tsconfig文件来隔离：
// tsconfig.json（基础配置） { "compilerOptions": { "strict": true, "esModuleInterop": true, "jsx": "react-jsx", "moduleResolution": "node", "baseUrl": ".", "paths": { "@/*": ["src/*"] } } }// tsconfig.web.json { "extends": "./tsconfig.json", "compilerOptions": { "lib": ["DOM", "ES2020"], "types": ["react", "react-dom"] }, "include": ["src/**/*.web.ts", "src/**/*.web.tsx", "src/**/*.ts", "src/**/*.tsx"] }// tsconfig.mobile.json { "extends": "./tsconfig.json", "compilerOptions": { "lib": ["ES2020"], "types": ["react-native"] }, "include": ["src/**/*.ios.ts", "src/**/*.android.ts", "src/**/*.ts", "src/**/*.tsx"] }然后在package.json的scripts里分别配置类型检查命令。这样在开发Web端时，TypeScript不会提示window不存在，开发移动端时也不会误用DOM API。
4.3 环境变量与配置管理
三端同构项目的环境变量管理需要区分两个维度：运行平台和部署环境。运行平台是iOS、Android、Web，部署环境是开发、测试、生产。这两个维度组合起来有九种情况，但实际配置通常只需要按部署环境区分，平台差异通过代码里的Platform.OS来处理。
我用的方案是基于react-native-config加上Web端的process.env注入。移动端通过.env文件加载配置，Web端通过Webpack的DefinePlugin注入：
// webpack.config.js const webpack = require('webpack'); const dotenv = require('dotenv'); const env = dotenv.config().parsed || {}; module.exports = { plugins: [ new webpack.DefinePlugin({ 'process.env': JSON.stringify({ API_BASE_URL: env.API_BASE_URL, APP_ENV: env.APP_ENV, }), }), ], };这样在代码里统一用process.env.API_BASE_URL访问，三端都能正常工作。
4.4 打包体积的优化策略
三端同构项目的一个潜在问题是打包体积膨胀，因为Web端可能引入了移动端不需要的polyfill，移动端也可能打包了Web端的代码。我的优化策略主要有三条：
第一条是按平台拆分第三方库。比如某个库只在Web端用，就把它放在platform目录下的Web实现文件里，移动端的打包不会包含它。Metro的tree shaking虽然不如Webpack强大，但通过合理的文件组织也能达到类似效果。
第二条是Web端做代码分割。React.lazy和动态import在Web端可以显著减少首屏加载体积，移动端则不需要这个，因为RN的打包本身就是全量加载。所以路由配置里，Web端用lazy加载页面组件，移动端直接import。
第三条是定期分析打包产物。移动端用react-native-bundle-visualizer，Web端用webpack-bundle-analyzer。我一般每个月跑一次分析，看看有没有意外引入的大体积依赖。
5. 常见问题与排查技巧实录
5.1 平台扩展名不生效的排查
这是三端同构项目里最常见的问题。你明明写了storage.web.ts，但Web端打包时还是用了storage.ts。排查思路按优先级排列：
首先检查Webpack的resolve.extensions配置，.web.ts必须在.ts前面。其次检查文件命名，必须是.web.ts而不是.web.tsx或者.web.js，扩展名要和实际文件类型一致。然后检查import语句，如果写的是import { storage } from './storage'，解析器会按extensions顺序查找；如果写的是import { storage } from './storage.ts'，那就直接锁定了文件，平台扩展名不会生效。
还有一个隐蔽的坑：如果storage.ts和storage.web.ts同时存在，但storage.ts里也导出了同名的方法，Webpack在某些配置下可能会优先解析到storage.ts。我的做法是平台特定文件不放在同一目录下与基础文件同名，而是用index.ts作为统一入口，平台文件放在子目录里。
5.2 样式在Web端错位的调试方法
RN的样式在Web端错位，通常是因为Flexbox的默认值不同。RN里View默认是display: flex; flex-direction: column，而Web的div默认是display: block。React Native Web做了适配，但某些情况下还是会有偏差。
调试这类问题的第一步是在浏览器开发者工具里检查实际渲染的CSS。React Native Web会把RN的样式转换成CSS类名，你可以看到具体的样式值。如果发现flex-direction不对，就在样式里显式声明。如果发现box-sizing不对，就在全局样式里加* { box-sizing: border-box; }。
我遇到过一个典型问题：RN里Text组件的numberOfLines属性在Web端不生效，文本还是会溢出。解决方案是在Web端用CSS的-webkit-line-clamp来实现：
// components/platform/Text/index.web.tsx export function Text({ numberOfLines, style, ...props }: TextProps) { const webStyle = numberOfLines ? { display: '-webkit-box', WebkitLineClamp: numberOfLines, WebkitBoxOrient: 'vertical', overflow: 'hidden', } : {}; return <span style={{ ...style, ...webStyle }} {...props} />; }5.3 第三方库兼容性速查表
| 库名 | iOS | Android | Web | 备注 |
|---|---|---|---|---|
| react-navigation | 支持 | 支持 | 部分 | Web端建议换React Router |
| react-native-reanimated | 支持 | 支持 | 不稳定 | Web端用CSS动画替代 |
| react-native-gesture-handler | 支持 | 支持 | 部分 | Web端手势支持有限 |
| async-storage | 支持 | 支持 | 不支持 | Web端用localStorage包装 |
| react-native-svg | 支持 | 支持 | 支持 | 三端表现一致 |
| react-native-maps | 支持 | 支持 | 不支持 | Web端用地图JS SDK |
| react-native-camera | 支持 | 支持 | 部分 | Web端用getUserMedia |
这个表是我在实际项目中逐步积累的，每次引入新库之前都会先查一下Web端支持情况。对于Web端不支持的库，要么找替代方案，要么做平台特定实现。
5.4 调试工具与日志策略
三端同构项目的调试比单端项目复杂，因为同一个bug可能只在某一个平台出现。我的调试策略是统一日志接口，分平台输出：
// common/utils/logger.ts import { Platform } from 'react-native'; type LogLevel = 'debug' | 'info' | 'warn' | 'error'; function log(level: LogLevel, message: string, ...args: unknown[]) { const timestamp = new Date().toISOString(); const prefix = `[${timestamp}][${Platform.OS}][${level.toUpperCase()}]`; if (__DEV__) { console[level](prefix, message, ...args); } // 生产环境可以接入远程日志服务 if (level === 'error') { // reportToServer(prefix, message, args); } } export const logger = { debug: (msg: string, ...args: unknown[]) => log('debug', msg, ...args), info: (msg: string, ...args: unknown[]) => log('info', msg, ...args), warn: (msg: string, ...args: unknown[]) => log('warn', msg, ...args), error: (msg: string, ...args: unknown[]) => log('error', msg, ...args), };这样在控制台里能一眼看出日志来自哪个平台，排查跨平台问题时非常有用。Web端还可以结合Chrome DevTools的断点调试，移动端用Flipper或者React Native Debugger。
实操心得：Web端的console日志在移动端Safari里可能会被截断，长对象建议用
JSON.stringify转成字符串再输出。另外，Android的logcat有日志长度限制，超长日志会被截断，重要信息要分段输出。
5.5 性能问题的跨平台排查思路
三端同构项目的性能问题需要分平台排查。Web端主要看首屏加载时间、交互响应延迟和内存占用，工具用Lighthouse和Chrome Performance面板。移动端主要看帧率、启动时间和内存泄漏，工具用Flipper和Xcode Instruments。
我遇到过一个典型问题：列表滚动在Web端卡顿，但在移动端很流畅。排查后发现是Web端的FlatList渲染了大量DOM节点，而移动端用的是原生回收机制。解决方案是在Web端用虚拟滚动库替代FlatList，或者限制initialNumToRender的值。
另一个常见问题是图片加载。移动端可以用react-native-fast-image做缓存，Web端用浏览器自带的缓存机制。但Web端的图片如果没设置合适的尺寸，会导致布局抖动。我的做法是在Web端给所有图片设置固定的宽高比容器，避免布局偏移。
6. 从开发到上线的完整工作流
6.1 本地开发环境的启动与切换
三端同构项目的本地开发需要同时启动多个服务。移动端用npx react-native start启动Metro，Web端用webpack serve或者vite启动开发服务器。我通常会在package.json里配置几个快捷命令：
{ "scripts": { "start:ios": "react-native run-ios", "start:android": "react-native run-android", "start:web": "webpack serve --config webpack.config.js", "typecheck:mobile": "tsc --noEmit -p tsconfig.mobile.json", "typecheck:web": "tsc --noEmit -p tsconfig.web.json", "typecheck": "npm run typecheck:mobile && npm run typecheck:web", "lint": "eslint src --ext .ts,.tsx", "test": "jest" } }开发时我一般会同时开三个终端：一个跑Metro，一个跑Webpack，一个跑类型检查的watch模式。这样任何一端出问题都能第一时间发现。
6.2 持续集成中的三端构建验证
CI流程需要覆盖三端的构建验证。我的配置是在每次提交时跑以下检查：TypeScript类型检查（移动端和Web端分别跑）、ESLint、单元测试、以及三端的打包构建。移动端的打包用react-native bundle命令验证，Web端用webpack --mode production验证。
# CI配置示例（伪代码） steps: - run: npm run typecheck - run: npm run lint - run: npm run test - run: npx react-native bundle --platform ios --dev false --entry-file index.js --bundle-output /tmp/ios.bundle - run: npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output /tmp/android.bundle - run: npm run build:web这样任何一端构建失败都能在合并前发现，避免把问题带到发布阶段。
6.3 灰度发布与回滚策略
三端同构项目的发布需要协调三个平台的节奏。移动端的发布要经过应用商店审核，Web端的发布是即时的。我的策略是Web端先发，移动端后发，因为Web端回滚成本低，可以快速验证新功能。
具体流程是：新功能先在Web端上线，观察一两天没有严重问题后，再提交移动端审核。如果Web端发现问题，直接回滚Web端即可，移动端不受影响。如果移动端审核期间发现问题，可以暂停发布，等修复后再重新提交。
注意：移动端的灰度发布可以用应用商店的分阶段发布功能，但Web端的灰度需要自己实现，通常是通过特性开关（Feature Flag）来控制。我一般会在配置服务里维护一个开关列表，Web端启动时拉取配置，根据开关决定是否启用新功能。
6.4 监控与错误上报的跨平台统一
三端同构项目的错误监控需要统一上报格式，方便在同一个面板里查看。我用的方案是封装一个ErrorReporter，三端都调用同一个接口，但底层实现不同：
// common/utils/errorReporter.ts interface ErrorContext { platform: string; appVersion: string; userId?: string; extra?: Record<string, unknown>; } export function reportError(error: Error, context?: Partial<ErrorContext>) { const fullContext: ErrorContext = { platform: Platform.OS, appVersion: APP_VERSION, ...context, }; // 三端统一调用远程上报接口 fetch(ERROR_REPORT_URL, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: error.message, stack: error.stack, context: fullContext, timestamp: Date.now(), }), }).catch(() => { // 上报失败时静默处理，不影响主流程 }); }Web端还可以额外接入window.onerror和unhandledrejection的全局捕获，移动端则用ErrorUtils.setGlobalHandler来捕获未处理的异常。
6.5 版本管理与依赖升级
三端同构项目的依赖管理需要格外小心，因为一个库的升级可能影响三个平台。我的原则是移动端和Web端的依赖版本尽量保持一致，特别是React和React Native相关的包。如果某个库在Web端需要不同版本，就用alias在Webpack配置里做替换，而不是在package.json里装两个版本。
升级依赖时，我会先在本地跑一遍三端的构建和核心功能测试，确认没问题后再提交。对于React Native的大版本升级，通常需要同步升级React Native Web的版本，这两个库的版本兼容性需要查官方文档确认。
7. 一些踩坑之后的经验总结
三端同构不是银弹，它解决的是代码复用和维护成本的问题，但引入了平台差异管理的复杂度。我在实际项目里最大的体会是：不要追求100%的代码复用率。有些平台特定的逻辑，强行抽象反而会让代码更难维护。我的经验值是，核心业务逻辑和状态管理可以做到90%以上的复用，UI组件大概70%左右，平台特定模块（如存储、导航、动画）可能只有50%的接口能统一。
另一个体会是TypeScript的类型定义要跟着平台差异走。不要为了追求类型统一而把平台特定的参数都塞进一个宽泛的接口里，那样会失去类型检查的意义。正确的做法是定义基础接口，平台特定实现可以扩展这个接口，但必须满足基础接口的约束。
最后，测试策略要覆盖三端。单元测试可以共享，但集成测试和UI测试需要分平台跑。我一般用Jest跑共享逻辑的单元测试，用Detox跑移动端的集成测试，用Playwright跑Web端的端到端测试。虽然测试成本高了点，但比起线上出问题再紧急修复，这个投入是值得的。
这个架构方案后续还可以继续演进，比如引入微前端的思想，把Web端拆成更细粒度的模块，或者用Server Components来优化Web端的首屏性能。但那是另一个话题了，先把当前这套跑稳，再考虑下一步的优化。
