使用EAS Build与EAS Update时的环境变量管理方案咨询

问题根源 #

EAS Build会自动读取eas.json对应profile的env配置并注入构建环境，所以app.config.ts能通过process.env.API_URL拿到值；但EAS Update默认不会自动加载eas.json的环境变量，导致更新包构建时无法获取API_URL，最终应用提示缺失。

最佳实践方案 #

1. 统一环境变量加载逻辑

先安装@expo/config（用于加载对应环境的配置文件）：

npm install @expo/config

修改app.config.ts，替换原有的import 'dotenv/config'，改为根据当前环境加载对应配置：

import { loadEnvConfig } from '@expo/config';

// 加载对应环境的.env文件，优先读取APP_ENV变量，默认用development
const projectRoot = __dirname;
loadEnvConfig(projectRoot, {
  env: process.env.APP_ENV || 'development',
});

// 后续代码保持不变
const runtimeVersion = '1.0.0';
const version = '1.0.0';
const EASProjectId = 'my-eas-project-id';
const scheme = 'com.myapp.mobile';

export default {
  expo: {
    // ...原有配置内容
    extra: {
      eas: { projectId: EASProjectId },
      API_URL: process.env.API_URL,
    },
  },
};

2. 分环境配置变量

可以选择两种方式管理环境变量：

方式A：本地.env文件（适合非敏感变量）

创建分环境的.env文件：

• .env.development：API_URL=https://dev.api.myapp.com
• .env.preview：API_URL=https://staging.api.myapp.com
• .env.production：API_URL=https://api.myapp.com

方式B：EAS Secrets（适合敏感变量，更安全）

在EAS控制台的项目Secrets中添加：

• API_URL_DEV：开发环境地址
• API_URL_STAGING：预览环境地址
• API_URL_PROD：生产环境地址

然后在eas.json的profile中引用这些Secrets：

"build": {
  "development": {
    "distribution": "internal",
    "android": {
      "gradleCommand": ":app:assembleDebug"
    },
    "ios": {
      "buildConfiguration": "Debug"
    },
    "env": {
      "APP_ENV": "development",
      "API_URL": "${API_URL_DEV}"
    }
  },
  "preview": {
    "node": "18.17.0",
    "channel": "staging",
    "distribution": "internal",
    "env": {
      "APP_PROFILE": "preview",
      "APP_CHANNEL": "staging",
      "APP_ENV": "preview",
      "API_URL": "${API_URL_STAGING}"
    }
  },
  "production": {
    "node": "18.17.0",
    "channel": "production",
    "distribution": "store",
    "env": {
      "APP_PROFILE": "production",
      "APP_CHANNEL": "production",
      "APP_ENV": "production",
      "API_URL": "${API_URL_PROD}"
    }
  }
}

3. 让EAS Update加载对应环境变量

修改eas.json，添加update配置块，绑定channel与环境变量：

{
  "cli": {
    "version": ">= 3.17.1"
  },
  "build": { ... }, // 保留原有build配置
  "update": {
    "preview": {
      "channel": "staging",
      "env": {
        "APP_ENV": "preview",
        "API_URL": "https://staging.api.myapp.com" // 或用Secrets: "${API_URL_STAGING}"
      }
    },
    "production": {
      "channel": "production",
      "env": {
        "APP_ENV": "production",
        "API_URL": "https://api.myapp.com" // 或用Secrets: "${API_URL_PROD}"
      }
    }
  },
  "submit": {
    "production": {}
  }
}

之后执行EAS Update时，指定对应profile即可自动加载环境变量：

# 发布到staging频道
eas update --platform ios --profile preview

# 发布到production频道
eas update --platform ios --profile production

4. 验证变量是否生效

安装expo-constants并添加调试代码，确认变量正确加载：

npm install expo-constants

在应用中添加：

import Constants from 'expo-constants';

// 调试时打印变量
console.log('当前API_URL:', Constants.expoConfig?.extra?.API_URL);

关键注意点 #

• 本地开发时，expo run:ios默认使用development环境，会加载.env.development
• 不要把包含敏感信息的.env文件提交到Git，用.gitignore忽略
• EAS Secrets中的变量会自动注入到EAS Build和Update的环境中，无需本地配置

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