在Expo项目中使用t3-env管理环境变量的最佳实践

t3-env是一个强大的TypeScript环境变量验证库，它可以帮助开发者在Expo项目中安全地管理和使用环境变量。本文将详细介绍如何在Expo项目中正确配置和使用t3-env。

环境变量配置方案

在Expo项目中，推荐采用以下结构来管理环境变量：

1. 创建一个env.ts文件作为环境变量的集中管理入口
2. 使用.env文件作为环境变量模板（提交到版本控制）
3. 使用.env.local文件存储实际值（加入.gitignore）

基本配置示例

在env.ts文件中，我们可以这样配置t3-env：

import { createEnv } from "@t3-oss/env-core";
import { z } from "zod";

export const env = createEnv({
  clientPrefix: "EXPO_PUBLIC_",
  client: {
    EXPO_PUBLIC_GOOGLE_MAPS_API_KEY: z.string().min(1),
    EXPO_PUBLIC_API_BASE_URL: z.string().url(),
  },
  runtimeEnv: {
    EXPO_PUBLIC_GOOGLE_MAPS_API_KEY: process.env.EXPO_PUBLIC_GOOGLE_MAPS_API_KEY,
    EXPO_PUBLIC_API_BASE_URL: process.env.EXPO_PUBLIC_API_BASE_URL,
  },
});

关键配置说明

1. clientPrefix: 设置为"EXPO_PUBLIC_"以匹配Expo的公共环境变量前缀要求
2. client: 定义客户端可访问的环境变量及其验证规则
3. runtimeEnv: 提供实际的环境变量值

TypeScript配置注意事项

在使用t3-env时，可能会遇到TypeScript模块解析问题。这通常是由于moduleResolution设置不当导致的。确保你的tsconfig.json配置正确：

{
  "extends": "expo/tsconfig.base",
  "compilerOptions": {
    "strict": true,
    "module": "ESNext"
  }
}

环境变量的使用

配置完成后，可以在项目中这样使用环境变量：

import { env } from "@/env";

const apiKey = env.EXPO_PUBLIC_GOOGLE_MAPS_API_KEY;

最佳实践建议

1. 始终为环境变量定义严格的验证规则
2. 区分公共和私有环境变量
3. 在开发和生产环境使用不同的.env文件
4. 将敏感信息排除在版本控制之外

通过以上配置，t3-env可以帮助Expo项目实现类型安全的环境变量管理，减少运行时错误，提高开发体验。