环境变量 – 运行时 | Bun 文档

Bun 会自动读取你的 .env 文件，并以惯用的方式提供以编程方式读取和写入环境变量的方法。此外，Bun 运行时行为的某些方面可以使用 Bun 特定的环境变量进行配置。

设置环境变量

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

.env
.env.production、.env.development、.env.test (取决于 NODE_ENV 的值)
.env.local

.env
FOO=hello
BAR=world

变量也可以通过命令行设置。

Linux/macOS

Windows

Linux/macOS
FOO=helloworld bun run dev

Windows
# Using CMD
set FOO=helloworld && bun run dev

# Using 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` 文件

Bun 支持 --env-file 来覆盖要加载的特定 .env 文件。你可以在 bun 运行时运行脚本时，或者在运行 package.json 脚本时使用 --env-file。

bun --env-file=.env.1 src/index.ts
bun --env-file=.env.abc --env-file=.env.def run build

引号

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

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

扩展

环境变量会自动扩展。这意味着你可以在环境变量中引用先前定义的变量。

.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`

一般来说，你不再需要 dotenv 或 dotenv-expand，因为 Bun 会自动读取 .env 文件。

读取环境变量

可以通过 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
<lots more lines>

TypeScript

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

Bun.env.whatever;
// string | undefined

为了获得自动完成并告诉 TypeScript 将变量视为非可选字符串，我们将使用接口合并。

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

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

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`，则运行时转译器会将转译输出缓存到指定的目录。如果 `BUN_RUNTIME_TRANSPILER_CACHE_PATH` 设置为空字符串或字符串 `"0"`，则运行时转译器将不缓存转译输出。如果未设置 `BUN_RUNTIME_TRANSPILER_CACHE_PATH`，则运行时转译器会将转译输出缓存到特定于平台的缓存目录。
`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 上，默认情况下启用崩溃报告上传。否则，截至 2024 年 5 月 21 日，遥测数据尚未发送，但我们计划在未来几周内添加遥测数据。如果 `DO_NOT_TRACK=1`，则自动上传崩溃报告和遥测数据都将被禁用。

运行时转译器缓存

对于大于 50 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

它缓存什么？

它缓存：

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

文件扩展名 .pile 用于这些缓存文件。