Vite 环境变量与 mode 分层约定

Vite 在 2021 年让很多前端项目重新感受到了“启动快”是什么体验，但真正进入团队协作后，第一个会乱掉的地方通常不是构建速度，而是环境变量文件。

尤其是中后台项目，接口地址、上传域名、监控开关、埋点配置都可能跟环境相关。如果没有约定，.env 很快就会越长越乱，最后谁也不敢改。

先把文件层次收清楚

我更习惯把职责分成四层：

• .env 放所有环境共用的默认值
• .env.development 放本地开发覆盖项
• .env.staging 放预发环境值
• .env.production 放正式环境值

这样做的好处，是每个文件只回答一个问题，而不是把所有变量都堆在一起。

前端变量要主动区分“可暴露”和“不可暴露”

Vite 在 2021 年已经把这个边界表达得很明确了，只有带 VITE_ 前缀的变量才会进入前端代码。这个约定非常重要，因为它能提醒团队：并不是所有配置都适合直接暴露到浏览器。

真正的密钥、签名、后端私有地址，不应该试图通过前端环境变量去解决。

不要让业务代码到处直接读 import.meta.env

如果页面、组件、工具函数里都散落着 import.meta.env.VITE_API_BASE_URL 这种写法，后面要统一改名或做兼容就会很难受。

更稳的方式是集中做一层配置出口，把环境变量解析、默认值和兜底逻辑都放进去。页面代码只依赖业务语义明确的配置对象。

mode 的价值不只是切换地址

很多团队一开始只把 mode 理解成“开发和生产不一样”。但在中后台场景里，预发联调、灰度演示、客户定制包都可能要求更细的环境区分。

mode 真正有用的地方，是让这些区分变成显式约定，而不是靠手动改文件。

小结

Vite 把环境变量体系做得足够轻，但轻不代表可以随便写。只要把文件分层、暴露边界和读取出口三件事先定清楚，后面的中后台项目维护成本会低很多。