React Native 环境配置：从开发到生产的完整指南

React Native 环境配置：从开发到生产的完整指南

在 React Native 项目开发中，合理的环境配置管理是确保应用在不同阶段正常运行的关键。本文将详细介绍如何在 React Native 项目中实现多环境配置，包括开发环境和生产环境的设置、切换方法以及常见问题的解决方案。

为什么需要环境配置？

在实际项目开发中，我们通常需要面对以下场景：

• 开发阶段：连接测试服务器，启用调试功能
• 测试阶段：使用测试数据，验证功能完整性
• 生产发布：连接正式服务器，优化性能和安全性

不同环境需要不同的配置参数，如 API 地址、超时时间、调试开关等。通过环境配置，我们可以在不修改代码的情况下，轻松切换不同的运行环境。

环境配置架构设计

文件结构

项目根目录/
├── .env                    # 默认环境配置
├── .env.development        # 开发环境配置
├── .env.production         # 生产环境配置
└── src/config/env.ts       # 环境配置处理逻辑

依赖安装

首先安装必要的依赖包：

npm install react-native-dotenv
npm install --save-dev @types/react-native-dotenv

Babel 配置

在 babel.config.js 中添加环境变量插件：

module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
  plugins: [
    [
      'module:react-native-dotenv',
      {
        moduleName: '@env',
        path: '.env',
        blacklist: null,
        whitelist: null,
        safe: false,
        allowUndefined: true,
      },
    ],
  ],
};

环境文件配置

默认配置 (.env)

# 默认环境配置（开发环境）
API_BASE_URL=http://dev-api.example.com:8082
API_TIMEOUT=10000
TOKEN_KEY=app_auth_token
APP_ENV=development

开发环境 (.env.development)

API_BASE_URL=http://dev-api.example.com:8082
API_TIMEOUT=10000
TOKEN_KEY=app_auth_token
APP_ENV=development

生产环境 (.env.production)

API_BASE_URL=http://prod-api.example.com:8081
API_TIMEOUT=15000
TOKEN_KEY=app_auth_token
APP_ENV=production

TypeScript 配置实现

创建类型安全的环境配置管理：

// src/config/env.ts
import {
  API_BASE_URL,
  API_TIMEOUT,
  TOKEN_KEY,
  APP_ENV,
} from '@env';

export interface EnvConfig {
  API_BASE_URL: string;
  API_TIMEOUT: number;
  TOKEN_KEY: string;
  APP_ENV: string;
}

// 环境配置实例
export const ENV: EnvConfig = {
  API_BASE_URL: API_BASE_URL || (__DEV__ ? 'http://dev-api.example.com:8082' : 'http://prod-api.example.com:8081'),
  API_TIMEOUT: parseInt(API_TIMEOUT || (__DEV__ ? '10000' : '15000'), 10),
  TOKEN_KEY: TOKEN_KEY || 'app_auth_token',
  APP_ENV: APP_ENV || (__DEV__ ? 'development' : 'production'),
};

// 辅助函数
export const isDevelopment = () => ENV.APP_ENV === 'development';
export const isProduction = () => ENV.APP_ENV === 'production';

export default ENV;

NPM Scripts 配置

在 package.json 中配置环境相关的脚本：

{
  "scripts": {
    // 运行应用（不同环境）
    "android": "react-native run-android",
    "android:dev": "ENVFILE=.env.development react-native run-android",
    "android:prod": "ENVFILE=.env.production react-native run-android --mode=release",
    "ios": "react-native run-ios",
    "ios:dev": "ENVFILE=.env.development react-native run-ios",
    "ios:prod": "ENVFILE=.env.production react-native run-ios --mode=Release",
    
    // 构建 APK（不同环境）
    "build:android": "cd android && ./gradlew assembleRelease && cd ..",
    "build:android:dev": "ENVFILE=.env.development cd android && ./gradlew assembleRelease && cd ..",
    "build:android:prod": "ENVFILE=.env.production cd android && ./gradlew assembleRelease && cd ..",
    "build:android:clean": "cd android && ./gradlew clean && cd ..",
    
    // Metro bundler
    "start": "react-native start",
    "start:reset": "react-native start --reset-cache"
  }
}

使用方法

开发调试

# 开发环境（默认）
npm run android

# 明确指定开发环境
npm run android:dev

# 生产环境测试
npm run android:prod

构建发布

# 构建开发版本 APK（快速测试）
npm run build:android:dev

# 构建生产版本 APK（正式发布）
npm run build:android:prod

# 清理构建缓存
npm run build:android:clean

代码中使用

import ENV, { isDevelopment, isProduction } from './src/config/env';

// 获取配置
console.log('API URL:', ENV.API_BASE_URL);
console.log('Timeout:', ENV.API_TIMEOUT);
console.log('Environment:', ENV.APP_ENV);

// 环境判断
if (isDevelopment()) {
  console.log('Running in development mode');
  // 开发环境特有逻辑
}

if (isProduction()) {
  console.log('Running in production mode');
  // 生产环境特有逻辑
}

配置对比分析

配置项	开发环境	生产环境	说明
API_BASE_URL	http://dev-api.example.com:8082	http://prod-api.example.com:8081	后端服务器地址
API_TIMEOUT	10000 (10秒)	15000 (15秒)	网络请求超时设置
APP_ENV	development	production	环境标识
调试模式	✅ 启用	❌ 禁用	__DEV__ 标志
代码混淆	❌ 禁用	✅ 启用	ProGuard/R8
签名方式	Debug 签名	Release 签名	安全性不同

开发工作流

日常开发流程

# 1. 启动开发环境
npm run android

# 2. 测试生产环境配置
npm run android:prod

# 3. 构建测试 APK
npm run build:android:dev

# 4. 构建发布 APK
npm run build:android:prod

常见问题与解决方案

环境变量未生效

问题现象：切换环境后，应用仍使用旧的配置

解决方案：

# 1. 清除 Metro 缓存
npm run start:reset

# 2. 清除构建缓存
npm run build:android:clean

# 3. 重新构建
npm run build:android:prod

网络连接问题

问题现象：APK 安装后提示网络连接失败

解决方案：

# 1. 检查服务器连通性
ping prod-api.example.com
curl -I http://prod-api.example.com:8081

# 2. 查看应用网络日志
adb logcat | grep -E "(Network|API|Connection)"

Android 网络安全配置：

创建 android/app/src/main/res/xml/network_security_config.xml：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">dev-api.example.com</domain>
        <domain includeSubdomains="true">prod-api.example.com</domain>
        <domain includeSubdomains="true">localhost</domain>
    </domain-config>
</network-security-config>

在 AndroidManifest.xml 中引用：

<application
  android:networkSecurityConfig="@xml/network_security_config"
  android:usesCleartextTraffic="true">
</application>

iOS 网络安全配置：

在 ios/项目名/Info.plist 中添加 App Transport Security 配置：

<key>NSAppTransportSecurity</key>
<dict>
    <!-- 允许任意加载（仅开发环境使用） -->
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    
    <!-- 或者指定特定域名（推荐生产环境） -->
    <key>NSExceptionDomains</key>
    <dict>
        <key>dev-api.example.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSExceptionMinimumTLSVersion</key>
            <string>TLSv1.0</string>
        </dict>
        <key>prod-api.example.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSExceptionMinimumTLSVersion</key>
            <string>TLSv1.0</string>
        </dict>
        <key>localhost</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

iOS 配置说明：

配置项	说明	使用场景
NSAllowsArbitraryLoads	允许所有 HTTP 连接	开发环境快速配置
NSExceptionDomains	指定特定域名例外	生产环境推荐使用
NSExceptionAllowsInsecureHTTPLoads	允许该域名的 HTTP 连接	HTTP API 服务器
NSExceptionMinimumTLSVersion	最低 TLS 版本要求	兼容旧版服务器

iOS 网络权限问题

问题现象：iOS 应用无法连接 HTTP 服务器

解决方案：

1. 开发环境快速配置（允许所有 HTTP）：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

2. 生产环境安全配置（推荐）：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSExceptionDomains</key>
    <dict>
        <key>your-api-domain.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
        </dict>
    </dict>
</dict>

Metro Bundler 问题

问题现象：Metro 启动失败或端口被占用

解决方案：

# 1. 停止所有 Metro 进程并重启
npm run start:reset

# 2. 检查端口占用
lsof -ti:8081 | xargs kill -9
npm start

最佳实践建议

1. 安全性考虑

• 敏感信息处理：避免在环境文件中存储密码、密钥等敏感信息
• 版本控制：当前配置适合团队协作，如有敏感信息可使用 .env.local
• Android 签名密钥：Release 签名密钥不应提交到版本控制
• iOS ATS 配置：生产环境避免使用 NSAllowsArbitraryLoads，应指定具体域名
• HTTPS 优先：生产环境尽量使用 HTTPS，减少 HTTP 例外配置

2. 团队协作

• 统一配置：团队成员使用相同的环境配置文件
• 文档维护：及时更新环境配置文档
• 测试覆盖：确保所有环境都经过充分测试

3. 部署策略

• 环境隔离：开发、测试、生产环境完全隔离
• 自动化构建：使用 CI/CD 自动化不同环境的构建流程
• 版本管理：为不同环境的构建版本做好标记

总结

通过合理的环境配置管理，我们可以：

1. 提高开发效率：快速切换不同环境进行开发和测试
2. 降低出错风险：避免因环境配置错误导致的问题
3. 简化部署流程：自动化不同环境的构建和部署
4. 增强团队协作：统一的配置标准便于团队协作

环境配置虽然看似简单，但在实际项目中却是保证应用稳定运行的重要基础。希望本文的介绍能帮助你在 React Native 项目中建立完善的环境配置管理体系。

---

本文基于 React Native 0.81.4 版本编写，不同版本可能存在差异，请根据实际情况调整。