> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 --define 实现构建时常量

`--define` 标志可以与 `bun build` 和 `bun build --compile` 一起使用，将构建时常量注入到您的应用程序中。这对于将构建版本、时间戳或配置标志等元数据直接嵌入编译后的可执行文件尤其有用。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/index.ts --outfile myapp
```

***

## 为什么使用构建时常量？

构建时常量直接嵌入到编译后的代码中，因此它们具有：

* **零运行时开销** – 不需要环境变量查找或文件读取
* **不可变** – 值在编译时烘焙进二进制文件
* **可优化** – 未使用的分支可以被死代码消除
* **安全** – 无需管理外部依赖或配置文件

这类似于 C/C++ 中的 `gcc -D` 或 `#define`，但适用于 JavaScript/TypeScript。

***

## 基本用法

### 使用 `bun build`

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 带构建时常量打包
bun build --define BUILD_VERSION='"1.0.0"' --define NODE_ENV='"production"' src/index.ts --outdir ./dist
```

### 使用 `bun build --compile`

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 带构建时常量编译为可执行文件
bun build --compile --define BUILD_VERSION='"1.0.0"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli
```

### JavaScript API

```ts build.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  define: {
    BUILD_VERSION: '"1.0.0"',
    BUILD_TIME: '"2024-01-15T10:30:00Z"',
    DEBUG: "false",
  },
});
```

***

## 常见用例

### 版本信息

将版本和构建元数据直接嵌入可执行文件：

<CodeGroup>
  ```ts src/version.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  // 这些常量在构建时被替换
  declare const BUILD_VERSION: string;
  declare const BUILD_TIME: string;
  declare const GIT_COMMIT: string;

  export function getVersion() {
    return {
      version: BUILD_VERSION,
      buildTime: BUILD_TIME,
      commit: GIT_COMMIT,
    };
  }
  ```

  ```sh Build command theme={"theme":{"light":"github-light","dark":"dracula"}}
  bun build --compile \
    --define BUILD_VERSION='"1.2.3"' \
    --define BUILD_TIME='"2024-01-15T10:30:00Z"' \
    --define GIT_COMMIT='"abc123"' \
    src/cli.ts --outfile mycli
  ```
</CodeGroup>

### 功能开关

使用构建时常量启用或禁用功能：

```ts src/version.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
// 在构建时被替换
declare const ENABLE_ANALYTICS: boolean;
declare const ENABLE_DEBUG: boolean;

function trackEvent(event: string) {
  if (ENABLE_ANALYTICS) {
    // 如果 ENABLE_ANALYTICS 为 false，整个代码块将被移除
    console.log("Tracking:", event);
  }
}

if (ENABLE_DEBUG) {
  console.log("调试模式已启用");
}
```

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
# 生产环境构建 - 启用分析，关闭调试
bun build --compile --define ENABLE_ANALYTICS=true --define ENABLE_DEBUG=false src/app.ts --outfile app-prod

# 开发环境构建 - 都启用
bun build --compile --define ENABLE_ANALYTICS=false --define ENABLE_DEBUG=true src/app.ts --outfile app-dev
```

### 配置

在构建时替换配置对象:

```ts src/version.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
declare const CONFIG: {
  apiUrl: string;
  timeout: number;
  retries: number;
};

// CONFIG 在构建时被替换为实际对象
const response = await fetch(CONFIG.apiUrl, {
  timeout: CONFIG.timeout,
});
```

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build --compile --define 'CONFIG={"apiUrl":"https://api.example.com","timeout":5000,"retries":3}' src/app.ts --outfile app
```

***

## 高级用法

### 不同环境的构建

为不同环境创建不同的可执行文件：

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "scripts": {
    "build:dev": "bun build --compile --define NODE_ENV='\"development\"' --define API_URL='\"http://localhost:3000\"' src/app.ts --outfile app-dev",
    "build:staging": "bun build --compile --define NODE_ENV='\"staging\"' --define API_URL='\"https://staging.example.com\"' src/app.ts --outfile app-staging",
    "build:prod": "bun build --compile --define NODE_ENV='\"production\"' --define API_URL='\"https://api.example.com\"' src/app.ts --outfile app-prod"
  }
}
```

### 使用 Shell 命令生成动态值

通过 Shell 命令生成构建时常量：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
# 使用 git 获取当前提交号和时间戳
bun build --compile \
  --define BUILD_VERSION="\"$(git describe --tags --always)\"" \
  --define BUILD_TIME="\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"" \
  --define GIT_COMMIT="\"$(git rev-parse HEAD)\"" \
  src/cli.ts --outfile mycli
```

### 构建自动化脚本

创建构建脚本自动注入构建元数据：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
// build.ts
import { $ } from "bun";

const version = await $`git describe --tags --always`.text();
const buildTime = new Date().toISOString();
const gitCommit = await $`git rev-parse HEAD`.text();

await Bun.build({
  entrypoints: ["./src/cli.ts"],
  outdir: "./dist",
  define: {
    BUILD_VERSION: JSON.stringify(version.trim()),
    BUILD_TIME: JSON.stringify(buildTime),
    GIT_COMMIT: JSON.stringify(gitCommit.trim()),
  },
});

console.log(`构建版本为 ${version.trim()}`);
```

***

## 重要注意事项

### 值的格式

值必须是有效的 JSON，将被解析并内联为 JavaScript 表达式：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
# ✅ 字符串必须用 JSON 引号包裹
--define VERSION='"1.0.0"'

# ✅ 数字是 JSON 字面量
--define PORT=3000

# ✅ 布尔值是 JSON 字面量
--define DEBUG=true

# ✅ 对象和数组（使用单引号包裹 JSON）
--define 'CONFIG={"host":"localhost","port":3000}'

# ✅ 数组也可以
--define 'FEATURES=["auth","billing","analytics"]'

# ❌ 以下写法无效 - 字符串缺少引号
--define VERSION=1.0.0
```

### 属性键名

你可以使用属性访问模式作为键，不仅限于简单标识符：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
# ✅ 替换 process.env.NODE_ENV 为 "production"
--define 'process.env.NODE_ENV="production"'

# ✅ 替换 process.env.API_KEY 为实际的密钥
--define 'process.env.API_KEY="abc123"'

# ✅ 替换嵌套属性
--define 'window.myApp.version="1.0.0"'

# ✅ 替换数组访问
--define 'process.argv[2]="--production"'
```

这对于环境变量特别有用：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
// 编译前
if (process.env.NODE_ENV === "production") {
  console.log("生产模式");
}

// 使用 --define 'process.env.NODE_ENV="production"' 编译后
if ("production" === "production") {
  console.log("生产模式");
}

// 优化后
console.log("生产模式");
```

### TypeScript 声明

对于 TypeScript 项目，声明常量以避免类型错误：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
// types/build-constants.d.ts
declare const BUILD_VERSION: string;
declare const BUILD_TIME: string;
declare const NODE_ENV: "development" | "staging" | "production";
declare const DEBUG: boolean;
```

### 跨平台兼容性

针对多个平台构建时，常量的用法相同：

```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
# Linux
bun build --compile --target=bun-linux-x64 --define PLATFORM='"linux"' src/app.ts --outfile app-linux

# macOS
bun build --compile --target=bun-darwin-x64 --define PLATFORM='"darwin"' src/app.ts --outfile app-macos

# Windows
bun build --compile --target=bun-windows-x64 --define PLATFORM='"windows"' src/app.ts --outfile app-windows.exe
```

***

## 相关链接

* [运行时定义常量](/guides/runtime/define-constant) - 在 `bun run` 中使用 `--define`
* [构建可执行文件](/bundler/executables) - `bun build --compile` 完整指南
* [打包器 API](/bundler) - 包含 `define` 选项的完整打包器文档