SST 项目中环境变量加载机制解析

环境变量加载机制详解

在 SST (Serverless Stack) 项目中，环境变量的加载机制是一个开发者经常需要关注的重要功能。SST 提供了灵活的环境变量管理方式，支持根据不同的部署阶段(stage)加载对应的环境变量文件。

多环境支持

SST 默认支持以下环境变量文件：

• .env - 基础环境变量文件
• .env.{stage} - 特定阶段的环境变量文件
• .env.local - 本地开发环境变量文件

当运行 sst dev 或 sst deploy 命令时，SST 会自动加载与当前阶段匹配的环境变量文件。例如，如果当前阶段是 dev，SST 会尝试加载 .env.dev 文件中的变量。

加载优先级

SST 的环境变量加载遵循以下优先级规则：

1. .env.{stage} 文件中的变量会覆盖 .env 中的同名变量
2. 显式通过 --stage 参数指定的阶段名称将决定加载哪个环境文件
3. 如果没有指定阶段，默认使用 dev 或 prod 阶段

常见问题解决方案

如果遇到环境变量未被正确加载的情况，可以检查以下几点：

1. 确保环境变量文件名与当前阶段名称完全匹配
2. 检查是否在命令中正确指定了 --stage 参数
3. 确认环境变量文件位于项目根目录
4. 验证环境变量文件格式是否正确（每行一个 KEY=VALUE 对）

最佳实践建议

1. 为每个部署阶段维护独立的环境变量文件
2. 敏感变量应使用 SST 的 Config 功能而非直接写在环境文件中
3. 在团队协作时，将 .env.local 添加到 .gitignore
4. 使用清晰的命名规范区分不同环境

通过理解 SST 的环境变量加载机制，开发者可以更高效地管理不同环境下的配置，确保应用在各个阶段都能正确运行。