企业官网建设流程全解析

React Native for Web 安装指南：从纯 Web 应用到多平台工程的完整起步方案

【免费下载链接】react-native-webCross-platform React UI packages项目地址: https://gitcode.com/gh_mirrors/re/react-native-web

本指南围绕 React Native for Web 官方文档中的 installation.md 展开，系统讲解如何安装react-native-web运行时与babel-plugin-react-native-web构建优化插件，并覆盖 Expo、Create React App 两条官方推荐的起步路径。阅读本文后，你将掌握在纯 Web 应用与既有 React Native 应用中接入 React Native for Web 的最小安装步骤、构建优化原理，以及把react-native别名到react-native-web的配置方法。

React Native for Web 是一套运行在浏览器中的 React 组件与 API 兼容层，其定位与项目描述一致：一套跨平台的 React UI 包。它既可以支撑多平台应用（与 React Native 原生工程共享代码），也可以用于纯 Web 应用；既可以被既有 React Web 应用增量采纳，也可以与既有 React Native 应用集成，同时还支持 Preact。本文所述安装内容均以当前仓库 packages/react-native-web/package.json（版本 0.21.1）为事实依据。

安装核心依赖

运行时依赖

React Native for Web 以 React 生态为前提，需要在项目中同时安装 React DOM 与react-native-web：

npm install react-dom react-native-web

根据 package.json 中的peerDependencies声明，react-native-web要求react与react-dom的版本为^18.0.0 || ^19.0.0，即 React 18 或 React 19 均可使用。同时main字段指向dist/cjs/index.js、module字段指向dist/index.js，这意味着现代打包器（webpack、Vite、Rollup 等）会优先消费 ES Module 产物，从而获得更优的 tree-shaking 效果。

构建优化：Babel 插件（推荐）

官方文档明确建议为构建期优化安装 Babel 插件，因为它承担两个关键职责：将react-native导入路径重写为react-native-web，并剔除应用未实际使用的模块（保持包体积最小）：

npm install --save-dev babel-plugin-react-native-web

插件的具体实现位于 packages/babel-plugin-react-native-web/src/index.js。从源码结构看，它通过getDistLocation将每个具名导入（如StyleSheet、View）重写为react-native-web/dist/exports/<name>的默认导入路径，从而让打包器只打包应用真正引用的模块；对于无法映射到moduleMap的导入，则回退到react-native-web/dist/index入口。插件还支持commonjs: true选项，用于将重写路径指向dist/cjs下的 CommonJS 构建，适用场景是那些默认消费 CommonJS 产物的打包器。

以 packages/babel-plugin-react-native-web/README.md 中的示例来说明重写效果：

// 重写前 import { StyleSheet, View } from 'react-native'; // 重写后 import StyleSheet from 'react-native-web/dist/exports/StyleSheet'; import View from 'react-native-web/dist/exports/View';

需要注意的是，react-native-web的内部路径并不稳定，官方明确告诫不要依赖这些内部路径，构建优化一律通过 Babel 插件完成。

快速开始：两条官方推荐路径

使用 Expo（官方首选）

Expo 是通用 React 应用的框架与平台。Expo for Web 底层即使用 React Native for Web，同时提供大量额外的跨平台 API、内置 Web 构建优化，并与更广泛的 React Native 生态兼容。官方文档将其定位为一般推荐方案，尤其是当你未来可能走向多平台时，Expo 会替你承担大量配置工作（详见 multi-platform.md 中的建议）。

使用 Create React App（纯 Web 起步）

Create React App 是搭建纯 Web React 应用的最简单方式之一，其内置了对把react-native-web别名到react-native的支持：

npx create-react-app my-app cd my-app npm install react-native-web npm start

需要指出的是，文档同时给出建议：一般情况下更推荐使用 Expo。Create React App 方案适合希望以最小成本获得一个纯 Web 应用、后续也不打算接入原生端的场景。

深入：从安装到跑通的关键配置

安装完成后，要让代码中的import ... from 'react-native'在 Web 端正确解析，还需要完成“别名”（aliasing）配置。这属于安装环节的天然延伸，官方在 setup.md 中给出了覆盖各工具的完整做法，这里摘录最核心的几种：

webpack 别名

// webpack.config.js module.exports = { // ...the rest of your config resolve: { alias: { 'react-native$': 'react-native-web' } } }

react-native$末尾的$表示仅精确匹配react-native这个模块名，避免误伤react-native-*系列子包。当前仓库的示例工程 react-native-web-examples/next.config.js 中，正是通过config.resolve.alias['react-native'] = 'react-native-web'这一行完成 Next.js 下的别名映射，可作为真实可运行的参考。

Babel 别名（babel-plugin-module-resolver）

{ "plugins": [ ["module-resolver", { "alias": { "^react-native$": "react-native-web" } }] ] }

Jest 测试别名

{ "moduleNameMapper": { "^react-native$": "react-native-web" } }

Flow 类型别名

[options] # Alias the package name module.name_mapper='^react-native$' -> 'react-native-web'

Node.js（预渲染 / SSR 场景）

如果你需要在 Node 环境中预渲染应用（例如服务端渲染或构建期渲染），可以使用module-alias包：

// 先安装 module-alias 作为依赖 const moduleAlias = require("module-alias"); moduleAlias.addAliases({ "react-native": require.resolve("react-native-web"), }); moduleAlias();

在既有 React Native 工程中集成

如果已有 React Native 应用，官方建议在多平台集成时优先参考 Expo 的实现，同时注意三点：使用Platform模块处理轻微的平台差异、使用*.web.js平台特定文件承载显著差异，以及在 webpack 中同时配置别名与.web.js扩展名解析。完整的多平台 webpack 配置示例（含 Babel loader 的include规则、图片 loader、入口与产物配置、extensions: ['.web.js', '.js']等）可在 multi-platform.md 中找到，这里不再赘述。

安装完成后的验证路径

用官方示例工程快速验证

仓库中附带了一个可直接对照运行的示例工程 react-native-web-examples，其pages目录下覆盖了view、text、text-input、image、pressable、modal等组件与 API 的演示页面。它的 next.config.js 提供了 webpack 别名配置的真实范本，适合安装后逐页对照验证组件行为。

确认已安装模块清单

安装成功后，可以通过 src/index.js 中导出的完整模块清单核对可用 API：包括View、Text、TextInput、Image、ScrollView、Pressable、Modal、Switch等核心组件，以及StyleSheet、Animated、AppRegistry、Dimensions、Platform、Linking、useWindowDimensions、useColorScheme等 API 与 Hooks。这些模块与 React Native 同名导出保持兼容，你的既有react-native导入语句无需改动即可在 Web 端复用。

给全屏应用的收尾样式

若你的应用是带根<ScrollView>的全屏布局，官方建议在 HTML 外壳中内联以下样式，保证根元素正确撑满视口且由 ScrollView 接管滚动：

/* These styles make the body full-height */ html, body { height: 100%; } /* These styles disable body scrolling if you are using <ScrollView> */ body { overflow: hidden; } /* These styles make the root element full-height */ #root { display:flex; height:100%; }

小结

本指南完整覆盖了官方安装文档的全部内容：运行时依赖react-dom+react-native-web的安装、Babel 插件babel-plugin-react-native-web的安装与构建优化原理（路径重写 + 按需模块裁剪）、Expo 与 Create React App 两条官方推荐的起步路径，并延伸讲解了安装后必需的别名配置与验证方法。当前仓库对应的版本为react-native-web@0.21.1，要求 React 18/19 与 React DOM 18/19。无论你的目标是纯 Web 应用，还是与既有 React Native 工程共享代码的多平台应用，上述安装与配置步骤都是后续开发的地基。

【免费下载链接】react-native-webCross-platform React UI packages项目地址: https://gitcode.com/gh_mirrors/re/react-native-web