# 环境变量与 .env 管理

Deno 默认不加载 `.env` 文件，需要显式选择加入。读取环境变量本身也受 `--allow-env` 权限约束。

## 加载 .env 文件

```bash
deno run --env-file main.ts            # 从当前目录向上查找第一个 .env
deno run --env-file=.env.local main.ts # 显式指定文件
```

- `--env-file` 可传入多次。同一文件内重复变量以第一次出现为准；多个文件之间，后指定的文件优先。
- 不授权 `.env` 的自动加载：CI 与生产环境应依赖平台注入的真实环境变量，而不是仓库里的文件。
- 需要在代码里手动加载时，可用标准库 `@std/dotenv`，但它仍需 `--allow-read` 与 `--allow-env`。

## 精确授权

```bash
deno run --allow-env=PORT,API_KEY main.ts
```

```ts title="main.ts"
const port = Number(Deno.env.get("PORT") ?? "8000");
if (!Number.isInteger(port)) throw new Error("PORT must be an integer");

const apiKey = Deno.env.get("API_KEY");
if (!apiKey) throw new Error("API_KEY is required");
```

启动时校验变量并立即失败，比请求中途遇到 `undefined` 更容易定位。只把程序真正读取的变量列入 `--allow-env`，第三方依赖无法借此偷看其余环境。

## 常用 DENO_* 运行时变量

| 变量 | 作用 |
| --- | --- |
| `DENO_DIR` | 依赖与编译缓存目录 |
| `DENO_NO_PACKAGE_JSON` | 关闭 `package.json` 自动解析 |
| `DENO_NO_PROMPT` | 禁止权限交互提示，等价于 `--no-prompt` |
| `DENO_NO_UPDATE_CHECK` | 关闭新版本检查 |
| `DENO_TLS_CA_STORE` | 证书来源，`system` / `mozilla`，默认 `mozilla` |
| `DENO_CERT` | 从 PEM 文件加载额外 CA，等价于 `--cert` |
| `DENO_AUTH_TOKENS` | 私有模块源的 Bearer 令牌 |
| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 模块下载与 `fetch` 的代理设置 |
| `NO_COLOR` | 关闭彩色输出 |

完整列表以官方文档为准；不要凭记忆在脚本里假设某个变量存在。

## 配置分层

按十二要素应用的原则，把随环境变化的值全部放进环境变量：

1. 代码里只允许非敏感的默认值（如 `PORT` 的 8000）。
2. 本地开发用 `.env`，并加入 `.gitignore`。
3. 仓库里提交 `.env.example`，列出键名与格式说明，不含真实值。
4. CI 与生产由平台注入变量，不读仓库中的 `.env`。

<Callout type="warn" title="密钥不进仓库、不进日志">
泄露过的密钥按“已泄露”处理：轮换并清理 git 历史，而不是只删最新提交。日志脱敏优先在输出层做——不要打印整个 `Deno.env.toObject()`，错误信息里也不要拼接令牌。
</Callout>

## 与 Deno Deploy 衔接

部署到 Deno Deploy 时，环境变量在控制台 app 的 **Environment Variables** 中维护，或用 `deno deploy env` 子命令管理（Classic 的 `deployctl` 已随平台关停，不要再用）：

```bash
deno deploy env add API_KEY "sk-..." --secret --org <org> --app <app>
deno deploy env load .env.production --org <org> --app <app>
```

`env add` 的 `--secret` 让值在 dashboard 与列表输出中不可见；`env load` 批量导入 `.env` 文件。代码侧仍然只读 `Deno.env.get()`，本地 `.env` 与平台变量使用同一组键名，代码就不感知部署形态。详见 [Deno Deploy](/docs/deploy/deno-deploy)。

官方参考：[Environment variables](https://docs.deno.com/runtime/reference/env_variables/)。