React+TypeScript跨移动端与Web端开发配置及相关问题咨询

我一直在研究相关内容，但可用信息有限。目前我正探索使用TypeScript编写可同时运行于移动端和Web端的React代码。我尝试过将react-native别名映射为react-native-web的技巧，但由于API并非100%一一对应，这种方法并非在所有场景下都适用。我还了解到可以通过编写.native.ts和.web.ts文件来实现平台专属代码。我的问题如下：

1. 若从零开始创建项目，能否告知需要安装哪些包以及如何配置，使项目能够识别用于移动端的.native.ts文件和用于Web端的.web.ts文件？
2. 在这类项目中，移动端和Web端代码会被打包到同一个bundle中吗？
3. 如果是，运行时（移动端设备或桌面浏览器）如何知晓应加载哪些文件（native或web）？

我已阅读过react-native-web的多平台文档，也了解过Expo，但我希望找到一种简洁的方案，让一个包同时包含移动端和Web端代码，并能被任一平台调用。因此我最关注第一个问题的答案，最好能提供一个示例应用来演示实现方式。

1. 从零搭建项目的包安装与配置 #

核心依赖安装 #

先初始化TypeScript项目，再安装跨平台核心依赖：

# 初始化项目
npm init -y
# 安装React跨平台核心包
npm install react react-dom react-native react-native-web
# 安装TypeScript及类型定义
npm install --save-dev typescript @types/react @types/react-dom @types/react-native
# 安装打包与转译工具
npm install --save-dev metro-react-native-babel-preset babel-loader webpack webpack-cli webpack-dev-server html-webpack-plugin @babel/preset-typescript module-resolver

关键配置文件设置 #

(1) TypeScript配置（tsconfig.json）

让TS识别平台专属文件后缀，同时配置基础路径映射：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "lib": ["ESNext", "DOM"],
    "jsx": "react-jsx",
    "strict": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "baseUrl": ".",
    "paths": {
      "react-native": ["node_modules/react-native-web"]
    },
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

(2) Babel配置（babel.config.js）

配置转译规则，支持平台文件后缀解析：

module.exports = {
  presets: [
    'module:metro-react-native-babel-preset',
    '@babel/preset-typescript'
  ],
  plugins: [
    [
      'module-resolver',
      {
        extensions: [
          '.web.tsx', '.web.ts', '.tsx', '.ts',
          '.web.jsx', '.web.js', '.jsx', '.js', '.json'
        ]
      }
    ]
  ]
};

(3) Webpack配置（webpack.config.js）

处理Web端打包，优先识别.web后缀文件：

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  entry: './src/index.web.tsx',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  resolve: {
    extensions: ['.web.tsx', '.web.ts', '.tsx', '.ts', '.web.jsx', '.web.js', '.jsx', '.js'],
    alias: {
      'react-native$': 'react-native-web'
    }
  },
  module: {
    rules: [
      {
        test: /\.(ts|tsx)$/,
        exclude: /node_modules/,
        use: 'babel-loader'
      }
    ]
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './public/index.html'
    })
  ],
  devServer: {
    static: {
      directory: path.join(__dirname, 'public')
    },
    port: 3000
  }
};

(4) Metro配置（metro.config.js）

处理React Native移动端打包，优先识别.native后缀文件：

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');

const config = {};
module.exports = mergeConfig(getDefaultConfig(__dirname), config);

示例项目结构 #

├── public/
│   └── index.html       # Web端入口HTML
├── src/
│   ├── components/
│   │   ├── Button.native.tsx   # 移动端专属按钮组件
│   │   ├── Button.web.tsx      # Web端专属按钮组件
│   ├── index.native.tsx        # 移动端入口文件
│   ├── index.web.tsx           # Web端入口文件
│   └── App.tsx                 # 通用业务组件
├── babel.config.js
├── metro.config.js
├── tsconfig.json
├── webpack.config.js
└── package.json

核心代码示例 #

• Web端入口（src/index.web.tsx）：

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(<App />);

• 移动端入口（src/index.native.tsx）：

import React from 'react';
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from '../app.json';

AppRegistry.registerComponent(appName, () => App);

• 通用业务组件（src/App.tsx）：

import React from 'react';
import Button from './components/Button';

const App = () => {
  return (
    <div>
      <Button onPress={() => alert('跨平台按钮触发')} />
    </div>
  );
};

export default App;

• Web端按钮（src/components/Button.web.tsx）：

import React from 'react';

interface ButtonProps {
  onPress: () => void;
}

const Button = ({ onPress }: ButtonProps) => {
  return (
    <button onClick={onPress} style={{ padding: '8px 16px', cursor: 'pointer' }}>
      Web端专属按钮
    </button>
  );
};

export default Button;

• 移动端按钮（src/components/Button.native.tsx）：

import React from 'react';
import { TouchableOpacity, Text, StyleSheet } from 'react-native';

interface ButtonProps {
  onPress: () => void;
}

const Button = ({ onPress }: ButtonProps) => {
  return (
    <TouchableOpacity style={styles.button} onPress={onPress}>
      <Text style={styles.text}>移动端专属按钮</Text>
    </TouchableOpacity>
  );
};

const styles = StyleSheet.create({
  button: {
    padding: 12,
    backgroundColor: '#2196F3',
    borderRadius: 4,
    margin: 20
  },
  text: {
    color: '#fff',
    textAlign: 'center',
    fontSize: 16
  }
});

export default Button;

启动脚本配置 #

在package.json中添加平台启动命令：

{
  "scripts": {
    "start:web": "webpack serve --mode development",
    "start:native": "react-native start",
    "android": "react-native run-android",
    "ios": "react-native run-ios",
    "build:web": "webpack --mode production"
  }
}

2. 移动端和Web端代码是否会打包到同一个bundle？ #

不会。Web端由Webpack打包生成独立的dist/bundle.js；移动端由Metro分别打包Android和iOS的专属bundle文件。两个平台的打包过程完全独立，各自只包含对应平台所需的代码。

3. 运行时如何识别加载对应平台的文件？ #

核心逻辑在打包阶段就完成了文件筛选：

• Webpack会优先解析.web.ts/.web.tsx后缀的文件；
• Metro会优先解析.native.ts/.native.tsx后缀的文件；
  当你在代码中导入import Button from './components/Button'时，打包工具会自动匹配当前平台对应的后缀文件，将对应代码打包进bundle，运行时直接加载筛选后的代码，无需额外判断。

内容的提问来源于stack exchange，提问作者Steve