简体中文
选择语言
简体中文Simplified Chinese繁體中文Traditional ChineseEnglishEnglish
安装 Bunv1.4.4
运行时包管理器打包器测试运行器代码检查格式化指南参考博客反馈

环境变量

在 Bun 中读取和配置环境变量，包括自动支持 .env 文件

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

设置环境变量

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

  • .env
  • .env.production, .env.development, .env.test（取决于 NODE_ENV 的值）
  • .env.local（当 NODE_ENV=test 时不会加载）
  • .env.production.local, .env.development.local, .env.test.local（取决于 NODE_ENV 的值）
.env
FOO=hello
BAR=world

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

Linux/macOS
FOO=helloworld bun run dev
Windows
# 使用 CMD
set FOO=helloworld && bun run dev

# 使用 PowerShell
$env:FOO="helloworld"; bun run dev
跨平台的 Windows 解决方案

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

shell
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 设置属性，以编程方式设置变量。

TypeScript
process.env.FOO = "hello";

手动指定 .env 文件

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

shell
bun --env-file=.env.1 src/index.ts

bun --env-file=.env.abc --env-file=.env.def run build

路径不必是常规文件。Bun 会读取管道、FIFO 或设备，直到输入结束，因此无需将密钥存储在磁盘文件中，也能将其传递给进程：

shell
bun --env-file=<(./fetch-secrets.sh) src/index.ts

echo "API_KEY=..." | bun --env-file=/dev/stdin src/index.ts

管道只能读取一次。Bun 会在进程启动时读取管道，Worker 线程和 bun test --parallel 工作进程会复用这些值。使用相同参数再次启动的进程会再次读取该路径：例如 --watch 重新加载，以及继承 execArgv 的 child_process.fork() 或 cluster.fork() 子进程。此时管道已为空，而 FIFO 会等待新的写入方，这与 Node.js 的情况相同。

禁用自动加载 .env

使用 --no-env-file 可禁用 Bun 自动加载 .env 文件，例如在生产环境或 CI/CD 流程中，如果你希望完全依赖系统环境变量。

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

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

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

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

当以 node 的身份调用时（例如通过 bun --bun、bunx --bun，或指向 Bun 的 node 符号链接调用），Bun 会禁用自动加载 .env，以匹配 Node.js 的行为。这样一来，Vite 的 loadEnv 等具有自身模式感知 .env 解析逻辑的工具，就可以选择正确的 .env.{mode} 文件，而不会将 Bun 预先填充的值视为由 shell 设置的覆盖值。Bun 仍会遵循显式指定的 --env-file 参数。

引号

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

.env
FOO='hello'
FOO="hello"
FOO=`hello`

扩展

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

.env
FOO=world
BAR=hello$FOO
TypeScript
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
TypeScript
process.env.BAR; // => "hello$FOO"

dotenv

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

读取环境变量

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

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

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

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

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

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

TypeScript

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

TypeScript
Bun.env.whatever;
// string | undefined

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

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

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

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

配置 Bun

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

名称描述
NODE_TLS_REJECT_UNAUTHORIZEDNODE_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，Bun 会将缓存写入该目录。如果将其设置为空字符串或字符串 "0"，则会禁用缓存。如果未设置，Bun 会将缓存写入平台特定的缓存目录。
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 上，默认启用崩溃报告上传。Bun 不会发送其他遥测数据，不过我们计划添加一些遥测数据。如果 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"。

shell
BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev

它缓存什么？

缓存内容包括：

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

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

编辑此页 基于 Bun 官方文档构建 · Bun v1.4.4