.env 的边界是什么
.env 文件是本地开发的便利工具：把环境变量写进文件、启动时加载。它不应进版本库、不同步生产；仓库里放 .env.example 只列键名不含值，生产环境由平台注入（环境变量、挂载、密钥管理）。事故模式几乎固定：「只差一行没提交」，整份带值文件进仓库，凭据从此跟着每个克隆扩散。
基本信息
| 本地 | .env 加加载库，快速启动开发 |
|---|---|
| 仓库 | .env.example 只列键不含值；.env 进 .gitignore |
| 生产 | 由平台注入（环境变量、挂载、密钥管理），不落地明文文件 |
| 工具 | dotenv 类库各有实现，加载与覆盖顺序要写进文档 |
| 启动校验 | 必填键缺失时直接失败，不带默认值硬跑 |
| 轮换 | 凭据轮换只改托管来源，不动本地文件 |
典型使用场景
- 本地开发：假凭据与本地端口，快速启动联调
- 新人上手：示例文件即配置清单，照键填充即可运行
- 本地覆盖：个人偏好键值不入库，机器之间隔离
- CI 对照：流水线变量与示例文件的键名对齐核对
- 巡检核对：定期扫描仓库，确认 .env 从未入库
- 流水线环境：密钥由平台注入，不依赖 .env 文件存在
.gitignore 与模板
.gitignore 与模板
.env
.env.local
.env.*.local
!.env.example # 只放行模板文件
# 若 .env 曾被提交：清理历史之外，务必先轮换其中的凭据各环境配置来源
| 环境 | 来源 | 注意 |
|---|---|---|
| 本地开发 | .env 加载 | .gitignore 兜底 |
| CI | 平台变量与密钥 | 键名对照示例文件 |
| 生产 | 平台或密钥管理注入 | 不落明文文件 |
| 容器 | 挂载或编排注入 | 镜像层不得含值 |
「只差一行没提交」的历史事故多是 .env：忽略规则加密钥扫描双保险，发现入库先轮换再清理。
加载顺序要明确：.env 与 .env.local 并存时谁覆盖谁要写进文档，避免「本机行为不一致」的幽灵问题。
示例文件更新即文档：新增键同步进示例文件，防止同伴本地启动失败。