环境变量

本文面向需要配置开发、测试或生产环境的研发和运维团队。商业版后端的很多问题最终都会回到配置本身，因此本文不只列变量，还说明：

• 哪些 .env 会被加载
• 哪些变量一定不能配错
• 开发环境和生产环境的重点差异是什么

加载顺序

后端按下面顺序加载环境变量，越靠前优先级越高：

.env.<NODE_ENV>.local
-> .env.local
-> .env.<NODE_ENV>
-> .env

建议按以下方式分层：

• 公共默认值：.env.development
• 当前开发机私有覆盖：.env.development.local
• 生产环境模板：.env.production

推荐的使用方式

文件	建议用途
.env.default.example	字段模板，不放真实密钥
.env.development	开发环境公共默认值
.env.development.local	本机私有配置，不建议共享
.env.production	生产环境配置或部署模板

必须优先确认的变量组

第一组：服务是否能够启动

• DATABASE_URL
• PORT
• ADMIN_PASSWORD
• ACCESS_TOKEN_SECRET
• REFRESH_TOKEN_SECRET

这一组如果有问题，服务通常不是直接启动失败，就是登录链路很快出问题。

第二组：前后端是否能够正常联调

• CORS_ENABLED
• CORS_ALLOWED_ORIGINS
• CORS_ALLOW_CREDENTIALS
• REFRESH_TOKEN_COOKIE_*
• SWAGGER_ENABLED

第三组：文件和项目能力是否能够落地

• STORAGE_PROVIDER
• STORAGE_BUCKET
• STORAGE_PUBLIC_BASE_URL
• 各云厂商密钥组

第四组：安全和增强能力

• API_SECURITY_ENABLED
• API_SIGNATURE_REQUIRED
• API_RSA_*
• THROTTLE_*
• AI_*

建议按业务理解变量，而不是死记名字

数据库相关

这组决定 Prisma 和业务服务连接哪个数据库。

鉴权相关

这组决定：

• Token 如何签发
• Cookie 如何下发
• 用户刷新令牌能否正常工作

API 安全相关

这组决定是否要求请求签名，以及签名校验的时间窗和密钥。

存储相关

这组决定文件中心能否真正接入对象存储。

AI 相关

这组决定 AI 助手是否能工作，以及接到哪个模型服务。

开发环境和生产环境的关注点不同

开发环境

更关注：

• 服务能否顺利启动
• 是否方便联调
• Swagger 是否开启
• CORS 是否足够宽松

生产环境

更关注：

• 密钥是否安全
• Cookie 是否符合域名和 HTTPS 策略
• CORS 是否收敛
• Swagger 是否应该关闭
• 存储和日志是否已配置完整

常见配置问题

只改了数据库密码，没改 DATABASE_URL

这是最常见的配置不一致问题。

后端能启动，但前端登录状态持续失效

通常是 REFRESH_TOKEN_COOKIE_*、域名或 HTTPS 策略不匹配。

生产环境接口全部跨域失败

通常是 CORS_ALLOWED_ORIGINS 没按真实域名配置。

文件上传接口正常，但访问链接不正确

通常是 STORAGE_PUBLIC_BASE_URL 或存储域名配置不正确。

检查清单

运行环境配置完成后，建议确认：

• .env.production 中没有使用开发默认密钥或默认管理员密码。
• CORS、Cookie、HTTPS 和前端 API 域名策略一致。
• 数据库、对象存储、日志、AI 等按实际功能范围完成配置。
• Swagger、签名、限流等安全相关开关符合部署环境要求。