> ## Documentation Index
> Fetch the complete documentation index at: https://bun.ll1025.cn/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={null}
FOO=hello
BAR=world
```

您也可以在命令行上设置变量。

<CodeGroup>
  ```sh Linux/macOS icon="terminal" theme={null}
  FOO=helloworld bun run dev
  ```

  ```sh Windows icon="windows" theme={null}
  # 使用 CMD
  set FOO=helloworld && bun run dev

  # 使用 PowerShell
  $env:FOO="helloworld"; bun run dev
  ```
</CodeGroup>

<Accordion title="Windows 的跨平台解决方案">
  对于跨平台解决方案，请使用 [Bun Shell](/runtime/shell)，例如通过 `bun exec`。

  ```sh theme={null}
  bun exec 'FOO=helloworld bun run dev'
  ```

  在 Windows 上，通过 `bun run` 调用的 `package.json` 脚本会自动使用 **Bun Shell**，因此以下代码也是跨平台的。

  ```json package.json icon="file-json" theme={null}
  "scripts": {
    "dev": "NODE_ENV=development bun --watch app.ts",
  },
  ```
</Accordion>

或者通过给 `process.env` 的属性赋值来以编程方式设置。

```ts theme={null}
process.env.FOO = "hello";
```

***

## 手动指定 `.env` 文件

`--env-file` 标志会覆盖 Bun 加载的 `.env` 文件。它既可以用于使用 `bun` 运行文件时，也可以用于运行 `package.json` 脚本时。

```sh theme={null}
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={null}
bun run --no-env-file index.ts
```

您也可以在 `bunfig.toml` 中禁用它：

```toml bunfig.toml icon="settings" theme={null}
# 禁用加载 .env 文件
env = false
```

即使禁用了默认加载，通过 `--env-file` 传递的文件仍会被加载。

***

## 引号

Bun 支持双引号、单引号和模板字面量反引号：

```ini .env icon="settings" theme={null}
FOO='hello'
FOO="hello"
FOO=`hello`
```

### 展开

Bun 会自动**展开**环境变量，因此您可以引用之前定义的变量。

```ini .env icon="settings" theme={null}
FOO=world
BAR=hello$FOO
```

```ts theme={null}
process.env.BAR; // => "helloworld"
```

这对于构建连接字符串或其他复合值非常有用。

```ini .env icon="settings" theme={null}
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={null}
FOO=world
BAR=hello\$FOO
```

```ts theme={null}
process.env.BAR; // => "hello$FOO"
```

### `dotenv`

Bun 会自动读取 `.env` 文件，因此不需要 `dotenv` 和 `dotenv-expand`。

## 读取环境变量

从 `process.env` 读取当前环境变量。

```ts theme={null}
process.env.API_TOKEN; // => "secret"
```

Bun 还将这些变量暴露为 `Bun.env` 和 `import.meta.env`，两者都是 `process.env` 的别名。

```ts theme={null}
Bun.env.API_TOKEN; // => "secret"
import.meta.env.API_TOKEN; // => "secret"
```

要打印所有当前设置的环境变量，请运行 `bun --print process.env`。

```sh theme={null}
bun --print process.env
BAZ=stuff
FOOBAR=aaaaaa
<更多行>
```

## TypeScript

在 TypeScript 中，`process.env` 的所有属性都被类型化为 `string | undefined`。

```ts theme={null}
Bun.env.whatever;
// string | undefined
```

要获得自动补全并告诉 TypeScript 将变量视为非可选字符串，请使用[接口合并](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces)。

```ts theme={null}
declare module "bun" {
  interface Env {
    AWESOME: string;
  }
}
```

将此声明添加到项目中的任何文件中。它会全局地将 `AWESOME` 属性添加到 `process.env` 和 `Bun.env`。

```ts theme={null}
process.env.AWESOME; // => string
```

## 配置 Bun

Bun 读取以下环境变量来配置其行为的各个方面。

| 名称                                       | 描述                                                                                                                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NODE_TLS_REJECT_UNAUTHORIZED`           | `NODE_TLS_REJECT_UNAUTHORIZED=0` 禁用 SSL 证书验证。对测试和调试很有用，但在生产环境中使用时请非常谨慎。Node.js 引入了此变量；Bun 保留此名称以保持兼容性。                                                                  |
| `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`      | 运行时转译器会缓存大于 4 KB 的源文件的转译输出，这使得使用 Bun 的 CLI 加载更快。如果设置了 `BUN_RUNTIME_TRANSPILER_CACHE_PATH`，缓存会写入该目录。如果设置为空字符串或字符串 `"0"`，则禁用缓存。如果未设置，缓存会写入平台特定的缓存目录。                      |
| `TMPDIR`                                 | Bun 有时需要一个目录来在打包或其他操作期间存储中间资源。如果未设置，默认为平台特定的临时目录：Linux 上为 `/tmp`，macOS 上为 `/private/tmp`。                                                                               |
| `NO_COLOR`                               | 如果 `NO_COLOR=1`，ANSI 颜色输出会被[禁用](https://no-color.org/)。                                                                                                                 |
| `FORCE_COLOR`                            | 如果 `FORCE_COLOR=1`，即使设置了 `NO_COLOR`，ANSI 颜色输出也会被强制启用。                                                                                                                   |
| `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 上，崩溃报告上传默认启用。不会发送其他遥测数据，尽管我们计划添加一些。如果 `DO_NOT_TRACK=1`，自动上传崩溃报告和遥测数据都会被[禁用](https://do-not-track.dev/)。                   |
| `BUN_OPTIONS`                            | 在任何 Bun 执行之前预置命令行参数。例如，`BUN_OPTIONS="--hot"` 使 `bun run dev` 的行为如同 `bun --hot run dev`。                                                                                 |

## 运行时转译器缓存

对于大于 4 KB 的文件，Bun 会将转译后的输出缓存到 `$BUN_RUNTIME_TRANSPILER_CACHE_PATH` 或平台特定的缓存目录。这使得使用 Bun 的 CLI 加载更快。

该缓存是全局的，在所有项目之间共享，并且是内容可寻址的，因此永远不会包含重复条目。随时可以安全删除，即使在 Bun 进程运行时也可以。

在使用 Docker 等临时文件系统时禁用此缓存。Bun 的 Docker 镜像会自动禁用它。

### 禁用运行时转译器缓存

要禁用运行时转译器缓存，请将 `BUN_RUNTIME_TRANSPILER_CACHE_PATH` 设置为空字符串或字符串 `"0"`。

```sh theme={null}
BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev
```

### 它缓存什么？

它缓存：

* 大于 4 KB 的源文件的转译输出。
* 文件转译输出的 sourcemap

缓存的文件使用 `.pile` 扩展名。