> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 环境变量
> 在 Bun 中读取和配置环境变量，包括自动支持 .env 文件
Bun 会自动读取你的 `.env` 文件，并提供符合习惯用法的方式以编程方式读取和写入环境变量。此外，Bun 运行时行为的某些方面可以通过 Bun 特定的环境变量进行配置。
## 设置环境变量
Bun 会自动读取以下文件（按优先级升序排列）。
* `.env`
* `.env.production`、`.env.development`、`.env.test`（取决于 `NODE_ENV` 的值）
* `.env.local`
```ini .env icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
FOO=hello
BAR=world
```
也可以通过命令行设置变量。
```sh Linux/macOS icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
FOO=helloworld bun run dev
```
```sh Windows icon="windows" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 使用 CMD
set FOO=helloworld && bun run dev
# 使用 PowerShell
$env:FOO="helloworld"; bun run dev
```
对于跨平台的解决方案，你可以使用 [bun shell](/runtime/shell)，例如 `bun exec` 命令。
```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun exec 'FOO=helloworld bun run dev'
```
在 Windows 上，使用 `bun run` 调用的 `package.json` 脚本会自动使用 **bun shell**，因此以下写法也兼容跨平台。
```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
"scripts": {
"dev": "NODE_ENV=development bun --watch app.ts",
},
```
或者通过给 `process.env` 赋值来编程设置。
```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
process.env.FOO = "hello";
```
***
## 手动指定 `.env` 文件
Bun 支持 `--env-file` 来覆盖加载的特定 `.env` 文件。你可以在运行 Bun 运行时的脚本时，或者运行 package.json 脚本时使用 `--env-file`。
```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --env-file=.env.1 src/index.ts
bun --env-file=.env.abc --env-file=.env.def run build
```
## 禁用自动加载 `.env`
使用 `--no-env-file` 可以禁用 Bun 自动加载 `.env` 文件。这在生产环境或 CI/CD 管道中仅依赖系统环境变量时非常有用。
```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun run --no-env-file index.ts
```
这也可以在 `bunfig.toml` 中配置：
```toml bunfig.toml icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 禁用加载 .env 文件
env = false
```
即使默认加载禁用，通过 `--env-file` 显式提供的环境文件仍然会被加载。
***
## 引号
Bun 支持双引号、单引号和模板字符串反引号：
```ini .env icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
FOO='hello'
FOO="hello"
FOO=`hello`
```
### 扩展
环境变量会被自动**展开**。这意味着你可以在环境变量中引用之前定义的变量。
```ini .env icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
FOO=world
BAR=hello$FOO
```
```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
process.env.BAR; // => "helloworld"
```
这对于构造连接字符串或其他复合值非常有用。
```ini .env icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
DB_USER=postgres
DB_PASSWORD=secret
DB_HOST=localhost
DB_PORT=5432
DB_URL=postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME
```
你也可以通过反斜杠转义 `$` 来禁用变量展开。
```ini .env icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
FOO=world
BAR=hello\$FOO
```
```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
process.env.BAR; // => "hello$FOO"
```
### `dotenv`
Bun 会自动读取 `.env` 文件，因此无需使用 `dotenv` 和 `dotenv-expand`。
## 读取环境变量
当前的环境变量可以通过 `process.env` 访问。
```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
process.env.API_TOKEN; // => "secret"
```
Bun 也通过 `Bun.env` 和 `import.meta.env` 暴露这些变量，它们都是 `process.env` 的别名。
```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.env.API_TOKEN; // => "secret"
import.meta.env.API_TOKEN; // => "secret"
```
要将所有当前设置的环境变量打印到命令行，可以运行 `bun --print process.env`，这对于调试非常有用。
```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --print process.env
BAZ=stuff
FOOBAR=aaaaaa
<更多行>
```
## TypeScript
在 TypeScript 中，`process.env` 的所有属性都被类型定义为 `string | undefined`。
```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
Bun.env.whatever;
// string | undefined
```
为了获得自动补全并告诉 TypeScript 将变量视为非可选字符串，我们可以使用 [接口合并](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces)。
```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
declare module "bun" {
interface Env {
AWESOME: string;
}
}
```
将此代码添加到项目中的任意文件中。它会全局为 `process.env` 和 `Bun.env` 添加 `AWESOME` 属性。
```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
process.env.AWESOME; // => string
```
## 配置 Bun
以下环境变量由 Bun 读取，并用于配置其行为的某些方面。
| 名称 | 描述 |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NODE_TLS_REJECT_UNAUTHORIZED` | 设置 `NODE_TLS_REJECT_UNAUTHORIZED=0` 会禁用 SSL 证书验证。这在测试和调试时非常有用，但你在生产环境中应极其谨慎使用。注意：该环境变量最初由 Node.js 引入，我们保留此名字以保证兼容性。 |
| `BUN_CONFIG_VERBOSE_FETCH` | 如果设置为 `BUN_CONFIG_VERBOSE_FETCH=curl`，fetch 请求将向控制台打印 url、方法、请求头和响应头，方便调试网络请求。该选项对 `node:http` 模块也有效。`BUN_CONFIG_VERBOSE_FETCH=1` 等同于 `BUN_CONFIG_VERBOSE_FETCH=curl`，但输出格式不含 curl 格式。 |
| `BUN_RUNTIME_TRANSPILER_CACHE_PATH` | 运行时转译器会缓存大于 50 KB 的源文件的转译输出，这可以加快使用 Bun 的 CLI 启动速度。如果设置了 `BUN_RUNTIME_TRANSPILER_CACHE_PATH`，运行时转译器会将缓存存储到指定目录。如果设置为空字符串或 `"0"`，则不会缓存。未设置时缓存存储在平台特定的缓存目录中。 |
| `TMPDIR` | Bun 有时需要一个目录来存储打包或其他操作期间的临时资产。如果未设置，则默认使用平台特定的临时目录：Linux 下为 `/tmp`，macOS 下为 `/private/tmp`。 |
| `NO_COLOR` | 如果设置为 `NO_COLOR=1`，则禁用 ANSI 彩色输出，详见 [no-color.org](https://no-color.org/)。 |
| `FORCE_COLOR` | 如果设置为 `FORCE_COLOR=1`，则强制启用 ANSI 彩色输出，即使 `NO_COLOR` 被设置。 |
| `BUN_CONFIG_MAX_HTTP_REQUESTS` | 控制 fetch 和 `bun install` 发送的最大并发 HTTP 请求数。默认值为 `256`。如果遇到速率限制或连接问题，可适当降低此数值。 |
| `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD` | 如果设置为 `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD=true`，则 `bun --watch` 在重载时不会清除终端。 |
| `DO_NOT_TRACK` | 禁用崩溃报告上传到 `bun.report`。在 macOS 和 Windows 上，崩溃报告上传默认启用。其他平台截至 2024 年 5 月 21 日尚未发送遥测，但计划在未来几周内添加。如果设置为 `DO_NOT_TRACK=1`，则自动上传崩溃报告和遥测都会被禁用，详见 [do-not-track.dev](https://do-not-track.dev/)。 |
| `BUN_OPTIONS` | 在任何 Bun 执行前预先添加命令行参数。例如，设置 `BUN_OPTIONS="--hot"` 会使 `bun run dev` 行为相当于执行 `bun --hot run dev`。 |
## 运行时转译器缓存
对于大于 50 KB 的文件，Bun 会将转译后的输出缓存到 `$BUN_RUNTIME_TRANSPILER_CACHE_PATH` 或平台特定的缓存目录，从而加快 Bun CLI 启动速度。
此转译器缓存是全局共享的，跨所有项目有效。可以随时安全删除缓存。因为它是内容寻址缓存，永远不会包含重复条目。即使在 Bun 进程运行时删除缓存也是安全的。
建议在使用类似 Docker 这样短暂文件系统时禁用此缓存。Bun 的 Docker 镜像会自动禁用该缓存。
### 禁用运行时转译器缓存
要禁用该缓存，将 `BUN_RUNTIME_TRANSPILER_CACHE_PATH` 设置为空字符串或字符串 `"0"`。
```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev
```
### 它缓存什么？
缓存内容包括：
* 大于 50 KB 源文件的转译输出。
* 转译输出对应的 sourcemap 文件。
缓存文件使用 `.pile` 扩展名。