环境变量

Bun 会自动读取你的 .env 文件，并提供符合惯用方式的 API，以便以编程方式读取和写入环境变量。你还可以使用 Bun 特有的环境变量来配置 Bun 运行时行为的部分内容。

设置环境变量

Bun 会自动读取以下文件（按优先级升序排列）。

.env
.env.production, .env.development, .env.test（取决于 NODE_ENV 的值）
.env.local

.env

FOO=hello
BAR=world

你也可以在命令行中设置变量。

FOO=helloworld bun run dev

# 使用 CMD
set FOO=helloworld && bun run dev

# 使用 PowerShell
$env:FOO="helloworld"; bun run dev

跨平台的 Windows 解决方案

如需跨平台解决方案，请使用 Bun Shell，例如通过 bun exec 使用。

bun exec 'FOO=helloworld bun run dev'

在 Windows 上，通过 bun run 调用的 package.json 脚本会自动使用 Bun Shell，因此以下方式同样支持跨平台。

package.json

"scripts": {
  "dev": "NODE_ENV=development bun --watch app.ts",
},

或者，通过为 process.env 设置属性，以编程方式设置变量。

process.env.FOO = "hello";

手动指定 `.env` 文件

--env-file 标志会覆盖 Bun 加载的 .env 文件。无论是使用 bun 运行文件，还是运行 package.json 脚本，都可以使用该标志。

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 流程中，如果你希望完全依赖系统环境变量。

bun run --no-env-file index.ts

你也可以在 bunfig.toml 中禁用此功能：

bunfig.toml

# 禁用加载 .env 文件
env = false

即使禁用了默认加载，通过 --env-file 传入的文件仍会被加载。当 Bun 以 node 的身份调用时（例如通过 bun --bun、bunx --bun，或指向 Bun 的 node 符号链接），会禁用自动加载 .env，以匹配 Node.js 的行为。这样，使用自身且感知运行模式的 .env 解析机制的工具（例如 Vite 的 loadEnv）就能正确选择 .env.{mode} 文件，而不会将 Bun 预先填充的值视为由 shell 设置的覆盖值。显式传入的 --env-file 参数仍会生效。

引号

Bun 支持双引号、单引号和模板字符串反引号：

.env

FOO='hello'
FOO="hello"
FOO=`hello`

扩展

Bun 会自动_扩展_环境变量，因此你可以引用之前定义的变量。

.env

FOO=world
BAR=hello$FOO

process.env.BAR; // => "helloworld"

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

.env

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

要禁用扩展，请使用反斜杠转义 $。

.env

FOO=world
BAR=hello\$FOO

process.env.BAR; // => "hello$FOO"

`dotenv`

Bun 会自动读取 .env 文件，因此无需使用 dotenv 和 dotenv-expand。

读取环境变量

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

process.env.API_TOKEN; // => "secret"

Bun 也通过 Bun.env 和 import.meta.env 暴露这些变量，它们都是 process.env 的别名。

Bun.env.API_TOKEN; // => "secret"
import.meta.env.API_TOKEN; // => "secret"

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

bun --print process.env
BAZ=stuff
FOOBAR=aaaaaa
<更多行>

TypeScript

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

Bun.env.whatever;
// string | undefined

要获得自动补全，并告诉 TypeScript 将变量视为非可选字符串，请使用接口合并。

declare module "bun" {
  interface Env {
    AWESOME: string;
  }
}

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

process.env.AWESOME; // => 字符串

配置 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`。除了不输出 `curl` 内容外，`BUN_CONFIG_VERBOSE_FETCH=1` 等同于 `BUN_CONFIG_VERBOSE_FETCH=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 颜色输出会被禁用。
`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 上，默认启用崩溃报告上传。不会发送其他遥测数据，不过我们计划添加一些。如果 `DO_NOT_TRACK=1`，则自动上传崩溃报告和遥测数据都会被禁用。
`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"。

BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev

它缓存什么？

缓存内容包括：

大于 4 KB 的源文件的转译输出。
文件转译输出的源映射。

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

开始使用

核心运行时

文件与模块系统

HTTP 服务器

网络通信

数据与存储

并发

进程与系统

交互与工具链

实用工具

标准与兼容性

贡献

设置环境变量

手动指定 `.env` 文件

禁用自动加载 `.env`

引号

扩展

`dotenv`

读取环境变量

TypeScript

配置 Bun

运行时转译器缓存

禁用运行时转译器缓存

它缓存什么？

​设置环境变量

​手动指定 .env 文件

​禁用自动加载 .env

​引号

​扩展

​dotenv

​读取环境变量

​TypeScript

​配置 Bun

​运行时转译器缓存

​禁用运行时转译器缓存

​它缓存什么？

设置环境变量

手动指定 `.env` 文件

禁用自动加载 `.env`

引号

扩展

`dotenv`

读取环境变量

TypeScript

配置 Bun

运行时转译器缓存

禁用运行时转译器缓存

它缓存什么？