Appearance
Bun 中的环境变量
环境变量是存储配置信息的重要方式，对于任何应用程序开发都至关重要。Bun 为环境变量提供了强大的支持，不仅自动读取.env文件，还提供了编程方式读写环境变量的便捷方法。
使用 Bun，您不再需要安装额外的`dotenv`或`dotenv-expand`这样的依赖包！
环境变量加载流程
当 Bun 运行时，它会按照以下优先顺序自动加载环境变量文件（优先级从低到高）：
.env (基础配置) → .env.[环境] (环境特定配置) → .env.local (本地配置)其中，.env.[环境]指的是根据NODE_ENV的值加载对应的文件：
.env.production（当NODE_ENV=production时）.env.development（当NODE_ENV=development时）.env.test（当NODE_ENV=test时）
INFO
环境变量加载原理 Bun 启动 → 读取基础.env 文件 → 根据 NODE_ENV 读取环境特定文件 → 读取本地覆盖配置 → 合并所有变量
设置环境变量的方法
方法 1：通过.env 文件
最常用的方法是创建一个.env文件：
txt
# .env文件示例
FOO=hello
BAR=world
API_KEY=your_secret_key
DEBUG=false方法 2：通过命令行
您可以在运行命令时直接设置环境变量：
sh
$ FOO=helloworld bun run devsh
$ set FOO=helloworld && bun run devsh
$ $env:FOO="helloworld"; bun run dev方法 3：跨平台解决方案
对于跨平台开发，Bun 提供了内置 shell 支持：
sh
$ bun exec 'FOO=helloworld bun run dev'在`package.json`的 scripts 中使用环境变量也是跨平台兼容的，因为`bun run`会自动使用 Bun shell！
json
{
"scripts": {
"dev": "NODE_ENV=development bun --watch app.ts"
}
}方法 4：编程方式设置
在代码中可以直接设置：
ts
process.env.FOO = "hello";
console.log(process.env.FOO); // 输出: hello手动指定.env 文件
有时您可能需要加载特定的环境文件，Bun 支持使用--env-file参数指定：
sh
# 加载单个特定环境文件
$ bun --env-file=.env.staging src/index.ts
# 加载多个环境文件
$ bun --env-file=.env.abc --env-file=.env.def run build环境变量格式指南
引号用法
Bun 支持多种引号格式来定义环境变量的值：
txt
# 以下三种引号方式都有效
FOO='hello'
FOO="hello"
FOO=`hello`变量展开（扩展）
Bun 自动支持环境变量的引用和展开，这是一个非常强大的功能：
txt
# 环境变量展开示例
FOO=world
BAR=hello$FOO # BAR将等于"helloworld"这个功能非常适合构建复杂的配置字符串，如数据库连接 URL：
txt
DB_USER=postgres
DB_PASSWORD=secret
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_URL=postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME如果你不想展开变量，可以使用反斜杠\进行转义：
txt
FOO=world
BAR=hello\$FOO # BAR将等于"hello$FOO"而不是"helloworld"读取环境变量
Bun 提供了多种方式来读取环境变量：
ts
// 以下三种方式完全等价
process.env.API_TOKEN; // 传统Node.js方式
Bun.env.API_TOKEN; // Bun特有方式
import.meta.env.API_TOKEN; // 另一种别名调试环境变量
要查看所有当前设置的环境变量，可以使用：
sh
$ bun --print process.env这对于调试环境变量问题非常有用。
TypeScript 中的环境变量支持
在 TypeScript 中，所有的process.env属性默认被类型为string | undefined：
ts
// 默认类型
Bun.env.API_KEY; // string | undefined增强环境变量类型支持
为了获得更好的代码补全和类型安全，可以使用 TypeScript 的接口合并功能：
ts
// 将此代码添加到项目中任意TypeScript文件
declare module "bun" {
interface Env {
API_KEY: string; // 必需的环境变量
DEBUG?: string; // 可选的环境变量
NODE_ENV: "development" | "production" | "test"; // 限制可能的值
}
}添加上述代码后，环境变量将获得更精确的类型：
ts
process.env.API_KEY; // 现在是string类型，而非string | undefined
process.env.NODE_ENV; // 现在是"development" | "production" | "test"类型Bun 配置相关的环境变量
以下是一些可以影响 Bun 行为的特殊环境变量：
| 环境变量 | 描述 | 默认值 |
|---|---|---|
NODE_TLS_REJECT_UNAUTHORIZED | 设置为0时禁用 SSL 证书验证，适用于测试环境 | 1(启用验证) |
BUN_CONFIG_VERBOSE_FETCH | 设置为curl或1启用网络请求详细日志 | 未设置 |
BUN_RUNTIME_TRANSPILER_CACHE_PATH | 指定转译缓存目录 | 平台特定缓存目录 |
TMPDIR | 指定临时文件目录 | Linux: /tmpmacOS: /private/tmp |
NO_COLOR | 禁用 ANSI 颜色输出 | 未设置 |
FORCE_COLOR | 强制启用 ANSI 颜色输出 | 未设置 |
BUN_CONFIG_MAX_HTTP_REQUESTS | 控制fetch和bun install的最大并发 HTTP 请求数 | 256 |
BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD | 设置为true时，bun --watch不会在重载时清除控制台 | 未设置 |
DO_NOT_TRACK | 设置为1时禁用崩溃报告上传和遥测 | 未设置 |
运行时转译缓存
Bun 会自动缓存大于 50KB 的转译文件输出，以加快加载速度。
txt
┌─────────────────┐ ┌───────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ 源文件(>50KB) │────▶│ Bun转译处理器 │────▶│ 转译后的代码 │
│ │ │ │ │ │
└─────────────────┘ └───────────────────┘ └────────┬────────┘
│
▼
┌─────────────────┐
│ │
│ 缓存目录 │
│ (.pile文件) │
│ │
└─────────────────┘缓存内容
转译缓存包含：
- 转译后的源文件输出
- 源码映射文件(sourcemap)
这些缓存文件使用.pile扩展名存储。
禁用转译缓存
在 Docker 等临时文件系统中，建议禁用此缓存：
sh
BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run devBun 的 Docker 镜像已自动禁用此缓存，无需额外配置。
最佳实践总结
- 项目级环境变量：使用多个
.env文件区分不同环境 - 敏感信息：将 API 密钥等敏感信息放在
.env.local中，并添加到.gitignore - 类型定义：为关键环境变量添加 TypeScript 类型定义
- 变量展开：利用变量展开功能创建复杂配置
- 跨平台兼容：在
package.json脚本中设置环境变量以获得跨平台支持
通过合理使用环境变量，您可以使您的 Bun 应用配置更灵活、更安全！