SST 项目中 .env 文件加载问题的排查与解决

问题背景

在使用 SST (Serverless Stack) 框架进行开发时，开发者遇到了环境变量文件(.env)无法被正确加载的问题。这个问题在从 0.1.17 版本升级到 0.1.80-0.1.88 版本后出现，但回退到旧版本后问题依然存在。

问题表现

1. 在 sst dev 命令运行时，环境变量未被正确加载
2. 在 sst.config.ts 文件中打印环境变量显示为 undefined
3. 尝试使用 dotenv 包手动加载环境变量也未能成功

排查过程

开发者首先尝试了以下排查步骤：

1. 版本回退：从新版本(0.1.80-0.1.88)回退到之前正常工作的 0.1.17 版本，但问题依然存在
2. 文件结构调整：移除 .env.[stage] 文件，仅保留 .env 文件，问题未解决
3. 手动加载尝试：使用 dotenv 包手动加载环境变量，依然失败

根本原因

经过深入排查，发现问题出在环境变量值中包含的双引号(")字符。虽然标准的 dotenv 包能够正常解析包含双引号的值，但在 SST 框架的环境变量加载机制中，这种特殊字符会导致解析失败。

解决方案

1. 检查所有环境变量值，特别是包含特殊字符的值
2. 对于必须包含双引号的值，考虑使用转义字符或单引号替代
3. 或者对值进行 Base64 编码，在使用时再解码

最佳实践建议

1. 环境变量命名规范：

   • 使用大写字母和下划线
   • 避免特殊字符
   • 保持名称简洁但具有描述性

2. 值处理建议：

   • 对于复杂值，考虑使用 JSON 字符串并转义
   • 或者将复杂配置移至专门的配置文件

3. 版本升级注意事项：

   • 在升级 SST 版本前，先在小规模测试环境中验证
   • 关注版本变更日志中关于环境变量处理的改动

总结

环境变量处理是 Serverless 应用开发中的常见痛点。SST 框架虽然提供了便捷的环境管理功能，但在特殊字符处理上可能有其特定的要求。开发者在使用时应特别注意环境变量值的格式规范，避免因特殊字符导致解析失败。当遇到类似问题时，建议从最简单的环境变量配置开始逐步测试，以快速定位问题根源。