配置

简介

Nylo Website v7 使用安全的环境配置系统。您的环境变量存储在 .env 文件中，然后加密到生成的 Dart 文件（env.g.dart）中以供应用使用。

这种方式提供了：

• 安全性：环境值在编译后的应用中进行 XOR 加密
• 类型安全：值自动解析为适当的类型
• 构建时灵活性：为开发、预发布和生产提供不同的配置

.env 文件

项目根目录中的 .env 文件包含您的配置变量：

# Environment configuration
APP_KEY=your-32-character-secret-key
APP_NAME="My App"
APP_ENV="developing"
APP_DEBUG=true
APP_URL="https://myapp.com"
API_BASE_URL="https://api.myapp.com"

ASSET_PATH="assets"

DEFAULT_LOCALE="en"

可用变量

生成环境配置

Nylo Website v7 要求您在应用访问环境值之前生成加密的环境文件。

步骤 1：生成 APP_KEY

首先，生成安全的 APP_KEY：

metro make:key

这会在您的 .env 文件中添加一个 32 位字符的 APP_KEY。

步骤 2：生成 env.g.dart

生成加密的环境文件：

metro make:env

这会创建包含加密环境变量的 lib/bootstrap/env.g.dart。

您的环境变量在应用启动时自动注册 — main.dart 中的 Nylo.init(env: Env.get, ...) 会为您处理。无需额外设置。

修改后重新生成

当您修改 .env 文件时，重新生成配置：

metro make:env --force

--force 标志会覆盖现有的 env.g.dart。

获取值

访问环境值的推荐方式是通过配置类。您的 lib/config/app.dart 文件使用 getEnv() 将环境值公开为有类型的静态字段：

// lib/config/app.dart
final class AppConfig {
  static final String appName = getEnv('APP_NAME', defaultValue: 'Nylo');
  static final String appEnv = getEnv('APP_ENV', defaultValue: 'developing');
  static final bool appDebug = getEnv('APP_DEBUG', defaultValue: false);
  static final String apiBaseUrl = getEnv('API_BASE_URL');
}

然后在您的应用代码中，通过配置类访问值：

// Anywhere in your app
String name = AppConfig.appName;
bool isDebug = AppConfig.appDebug;
String apiUrl = AppConfig.apiBaseUrl;

这种模式将环境访问集中在您的配置类中。getEnv() 辅助函数应在配置类中使用，而不是直接在应用代码中使用。

创建配置类

您可以使用 Metro 为第三方服务或特定功能的配置创建自定义配置类：

metro make:config RevenueCat

这会在 lib/config/revenue_cat_config.dart 创建一个新的配置文件：

final class RevenueCatConfig {
  // Add your config values here
}

示例：RevenueCat 配置

步骤 1： 将环境变量添加到您的 .env 文件中：

REVENUECAT_API_KEY="appl_xxxxxxxxxxxxx"
REVENUECAT_ENTITLEMENT_ID="premium"

步骤 2： 更新您的配置类以引用这些值：

// lib/config/revenue_cat_config.dart
import 'package:nylo_framework/nylo_framework.dart';

final class RevenueCatConfig {
  static final String apiKey = getEnv('REVENUECAT_API_KEY');
  static final String entitlementId = getEnv('REVENUECAT_ENTITLEMENT_ID', defaultValue: 'premium');
}

步骤 3： 重新生成您的环境配置：

metro make:env --force

步骤 4： 在您的应用中使用配置类：

import '/config/revenue_cat_config.dart';

// Initialize RevenueCat
await Purchases.configure(
  PurchasesConfiguration(RevenueCatConfig.apiKey),
);

// Check entitlements
if (entitlement.identifier == RevenueCatConfig.entitlementId) {
  // Grant premium access
}

这种方式使您的 API 密钥和配置值保持安全和集中，便于在不同环境中管理不同的值。

变量类型

.env 文件中的值会自动解析：

环境风味

为开发、预发布和生产创建不同的配置。

步骤 1：创建环境文件

创建单独的 .env 文件：

.env                  # Development (default)
.env.staging          # Staging
.env.production       # Production

.env.production 示例：

APP_KEY=production-secret-key-here
APP_NAME="My App"
APP_ENV="production"
APP_DEBUG=false
APP_URL="https://myapp.com"
API_BASE_URL="https://api.myapp.com"

步骤 2：生成环境配置

从特定的环境文件生成：

# For production
metro make:env --file=".env.production" --force

# For staging
metro make:env --file=".env.staging" --force

步骤 3：构建您的应用

使用相应的配置进行构建：

# Development
flutter run

# Production build
metro make:env --file=.env.production --force
flutter build ios
flutter build appbundle

构建时注入

为了增强安全性，您可以在构建时注入 APP_KEY，而不是将其嵌入源代码中。

使用 --dart-define 模式生成

metro make:env --dart-define

这会生成不嵌入 APP_KEY 的 env.g.dart。

使用 APP_KEY 注入构建

# iOS
flutter build ios --dart-define=APP_KEY=your-secret-key

# Android
flutter build appbundle --dart-define=APP_KEY=your-secret-key

# Run
flutter run --dart-define=APP_KEY=your-secret-key

这种方式将 APP_KEY 保留在源代码之外，适用于：

• 注入密钥的 CI/CD 管道
• 开源项目
• 增强安全性要求

最佳实践

1. 永远不要将 .env 提交到版本控制 - 将其添加到 .gitignore
2. 使用 .env-example - 提交一个不包含敏感值的模板
3. 修改后重新生成 - 修改 .env 后始终运行 metro make:env --force
4. 每个环境使用不同的密钥 - 为开发、预发布和生产使用唯一的 APP_KEY