无侵入增强 React Native 组件：Babel + Proxy + Shim 方案总览

在 React Native 里，有时需要对官方组件做「无侵入」增强：不改业务代码的 import，不 patch RN 内部 API，又能让 Text、View、Image、Pressable 等具备额外能力（例如修复 Android 吞字、统一阴影、替换为 FastImage、按钮防抖、限制系统字体缩放等）。

本方案通过 Babel 别名 + react-native-proxy + Shim 组件 实现：打包时把对 react-native 的引用指到自建的 proxy，proxy 对指定组件返回 Shim，Shim 内部再使用真实 RN 并注入或包装逻辑。业务侧继续写 import { Text, View } from 'react-native' 即可，类型也仍从 react-native 解析，无需为 Shim 单独写类型。

本文是这一系列做法的总览：说明整体流程、目录约定、如何新增一个 Shim、如何配合 TypeScript，并索引到各篇专题文章。

为什么用这套方案

不依赖 RN 内部实现：不改 Text.render、View.render 等，避免在 RN 升级后失效（如 0.66+ 吞字 patch 失效）。
业务零改动：业务继续 import { Text, View, Image, Pressable } from 'react-native'，无需改成从别的路径引入「增强版」组件。
兼容版本范围大：从低版本到高版本 RN 均可使用，不依赖新架构。
可叠加多种增强：同一套 proxy 可同时代理 Text、View、Image、Pressable 等，各 Shim 互不干扰；TypeScript 上通过 react-native.d.ts 按需扩展自定义 props。

整体流程

react-native-shim-overview-2026-02-10-00-01-16

目录与文件约定

可按项目习惯调整，以下为常见约定：

角色	路径示例	说明
Babel 配置	`babel.config.js`	在 `module-resolver` 的 `alias` 中配置 `'^react-native$': './app/utils/react-native-proxy.js'`
Proxy	`app/utils/react-native-proxy.js`	从真实 RN 做一层 Proxy，对指定 `prop` 返回对应 Shim
Shim 组件	`app/utils/shim/TextShim.tsx`、`ViewShim.tsx` 等	从 `../../node_modules/react-native` require 真实组件，包装或改写后导出
公共逻辑	`app/utils/shim/font-helpers.ts`、`debounce-helpers.ts` 等	供多个 Shim 复用的工具函数
类型扩展	项目根目录 `react-native.d.ts`	`declare module 'react-native'` 扩展 Props，并 `export from 'react-native'`

Proxy 和 Shim 里引用「真实 react-native」时，请使用绝对路径或相对路径指向 node_modules/react-native，不要再用模块名 'react-native'，否则会再次走到 proxy 造成循环。

如何新增一个 Shim

安装并配置 Babel（module-resolver）
本方案依赖 Babel 的 module-resolver 插件，把对 react-native 的引用解析到项目内的 proxy 文件。若尚未安装与配置：

安装：

yarn add -D babel-plugin-module-resolver

配置： 在 babel.config.js 的 plugins 中加入 module-resolver，并在其 alias 里将 react-native 指向 proxy 文件路径（路径按项目结构调整，例如 proxy 在 app/utils/ 下）：

// babel.config.js
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    [
      'module-resolver',
      {
        root: ['./'],
        extensions: ['.ts', '.tsx', '.ios.js', '.android.js', '.js', '.json'],
        alias: {
          '^react-native$': './app/utils/react-native-proxy.js',
          // ... 其他 alias
        },
      },
    ],
  ],
};

在 proxy 里增加分支
在 react-native-proxy.js 的 get(target, prop) 中，为要增强的组件增加判断，例如对 TextInput 返回 TextInputShim：

// app/utils/react-native-proxy.js
const RN = require('../../node_modules/react-native');

module.exports = new Proxy(RN, {
  get(target, prop) {
    if (prop === 'View') {
      if (!module.exports.__ViewShim) {
        module.exports.__ViewShim = require('./shim/ViewShim').default;
      }
      return module.exports.__ViewShim;
    }
    // Text、Image、TextInput、Pressable、TouchableOpacity 等同理，需则增加对应分支
    return target[prop];
  },
});

实现 Shim 组件
新建 app/utils/shim/TextInputShim.tsx（或复用已有），内部从真实 RN 取组件并渲染，在 props/style 上做你需要的增强：

const RN = require('../../node_modules/react-native');

const TextInputShim = (props: TextInputProps) => {
  // 按需改写 props、style，或包一层别的组件
  return <RN.TextInput {...processedProps} />;
};
export default TextInputShim;

若有自定义 props
在项目根目录的 react-native.d.ts 里扩展对应 *Props 接口，并保留 export * from 'react-native'，这样 TypeScript 和 IDE 能识别新 props。例如：
react-native.d.ts 其实可以放在和 react-native-proxy.js 同级目录下，只要能被 TypeScript 识别到即可。

// react-native.d.ts
import 'react-native';

declare module 'react-native' {
  export interface TextInputProps {
    customProp?: string;
  }
}

本系列专题文章索引

文章	解决的问题
如何在 React Native 中处理 Android 手机吞字问题	通过 TextShim 注入默认 `fontFamily`（或空字符串），避免部分 Android 机型上文字显示不全。
如何在 React Native 中实现无侵入式的阴影效果	通过 ViewShim 在 Android 上用 `react-native-drop-shadow` 实现与 iOS 一致的 `shadowRadius` / `shadowOffset` / `shadowOpacity`。
如何使用 FastImage 无侵入替换 React Native 的 Image	通过 ImageShim 用 FastImage 渲染，并透传 `resolveAssetSource`、`prefetch`、`getSize` 等静态方法。
如何无侵入式地为 React Native 按钮添加防抖功能	通过 PressableShim / Touchable*Shim 支持 `debounceTime`、`debounceDisabled`、`pending`，并用 `react-native.d.ts` 让 TypeScript 感知这些属性。
如何无侵入式地应对系统放大字体与屏幕缩放	通过 TextShim / TextInputShim 设置 `maxFontSizeMultiplier` 与 `fontSizeToFit`，限制系统大号字体和小屏下的放大效果。
如何无侵入增强 TextInput，解决 lineHeight + placeholder 导致输入首字时高度变动	通过 TextInputShim 用外层 View + 绝对定位 placeholder Text，避免原生 placeholder 与首字切换时高度跳动。

上述各篇在 Babel 与 proxy 的配置上一致，可共用同一套 react-native-proxy.js；按需阅读对应专题即可实现单一能力，或组合多种增强。

# 无侵入增强 React Native 组件：Babel + Proxy + Shim 方案总览

# 为什么用这套方案

# 整体流程

# 目录与文件约定