将Expo应用上传至TestFlight后.env文件无法加载的问题

核心原因 #

eas build的生产构建（TestFlight使用Release配置）不会自动将本地.env文件的变量注入到安装包中，必须通过Expo的配置体系传递变量，不能直接依赖process.env在运行时读取。

具体解决步骤 #

1. 配置依赖与app.config.js #

先安装必要依赖：

npm install expo-constants @expo/config-plugins

将app.json替换为app.config.js（若未替换），通过dotenv读取.env变量并放入expo配置的extra字段：

import 'dotenv/config';

export default {
  expo: {
    name: '你的应用名称',
    slug: 'your-app-slug',
    ios: {
      bundleIdentifier: 'com.yourcompany.yourapp',
      buildNumber: '1.0.1'
    },
    extra: {
      // 列出所有需要的.env变量
      API_BASE_URL: process.env.API_BASE_URL,
      APP_KEY: process.env.APP_KEY
    }
  }
};

2. 配置eas.json确保构建时加载环境变量 #

在项目根目录的eas.json中，为production构建profile添加env配置，确保构建时读取.env文件：

{
  "build": {
    "production": {
      "ios": {
        "buildConfiguration": "Release"
      },
      "env": {
        // ${env:XXX}会自动读取本地.env里的XXX变量
        "API_BASE_URL": "${env:API_BASE_URL}",
        "APP_KEY": "${env:APP_KEY}"
      }
    }
  }
}

如果区分环境（如staging、production），可创建.env.production、.env.staging文件，构建时通过--profile staging指定，eas会自动读取对应环境的.env文件。

3. 代码中正确获取变量 #

不要直接使用process.env，改用expo-constants读取配置：

import Constants from 'expo-constants';

// 加兜底值避免undefined导致报错
const API_BASE_URL = Constants.expoConfig?.extra?.API_BASE_URL || '默认接口地址';
const APP_KEY = Constants.expoConfig?.extra?.APP_KEY || '';

4. 构建与验证 #

执行构建命令时指定production profile：

eas build --platform ios --profile production

构建完成后，可查看构建日志的"Expo config"部分，确认extra字段的变量是否正确。也可在TestFlight版本中添加临时调试弹窗，打印这些变量验证是否加载成功。

5. 常见问题排查 #

• 检查.env文件是否在项目根目录，是否被.gitignore意外排除（构建时本地.env会被读取，无需提交到git）
• 确保变量名拼写完全一致，比如.env里是API_BASE_URL，app.config.js里不能写成API_URL
• 升级eas-cli到最新版本，旧版本可能存在env注入bug：npm install -g eas-cli

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