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

# 安装

> 通过 npm、Homebrew、Docker 或官方脚本安装 Bun。

## 概述

Bun 以单个无依赖的可执行文件形式发布。你可以通过脚本、包管理器或 Docker 在 macOS、Linux 和 Windows 上安装。

<Tip>安装后，请使用 `bun --version` 和 `bun --revision` 进行验证。</Tip>

## 安装

<Tabs>
  <Tab title="macOS & Linux">
    <CodeGroup>
      ```bash curl icon="globe" theme={"theme":{"light":"github-light","dark":"dracula"}}
      curl -fsSL https://bun.com/install | bash
      ```
    </CodeGroup>

    <Note>
      **Linux 用户**：安装 Bun 需要 `unzip` 包。使用 `sudo apt install unzip` 安装 unzip 包。建议使用 5.6 或更高版本的内核；Bun 也可在更早的 3.10（RHEL 7）内核上运行，并会对较新的系统调用进行优雅降级。使用 `uname -r` 查看你的内核版本。
    </Note>
  </Tab>

  <Tab title="Windows">
    <CodeGroup>
      ```powershell PowerShell icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
      powershell -c "irm bun.sh/install.ps1|iex"
      ```
    </CodeGroup>

    <Warning>
      Bun 需要 Windows 10 版本 1809 或更高。
    </Warning>

    如需支持和讨论，请加入我们的 [Discord](https://bun.com/discord) 上的 **#windows** 频道。
  </Tab>

  <Tab title="包管理器">
    <CodeGroup>
      ```bash npm icon="npm" theme={"theme":{"light":"github-light","dark":"dracula"}}
      npm install -g bun # 这是你最后一次需要运行的 npm 命令
      ```

      ```bash Homebrew icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/homebrew.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=41bb4552d95e0853b4d6a2f9aa3906ab" theme={"theme":{"light":"github-light","dark":"dracula"}}
      brew install oven-sh/bun/bun
      ```

      ```bash Scoop icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
      scoop install bun
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Docker">
    Bun 提供支持 Linux x64 和 arm64 的 Docker 镜像。

    ```bash Docker icon="docker" theme={"theme":{"light":"github-light","dark":"dracula"}}
    docker pull oven/bun
    docker run --rm --init --ulimit memlock=-1:-1 oven/bun
    ```

    ### 镜像变体

    还有针对不同操作系统的镜像变体：

    ```bash Docker icon="docker" theme={"theme":{"light":"github-light","dark":"dracula"}}
    docker pull oven/bun:debian
    docker pull oven/bun:slim
    docker pull oven/bun:distroless
    docker pull oven/bun:alpine
    ```
  </Tab>
</Tabs>

要确认 Bun 是否成功安装，请打开一个新终端窗口并运行：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --version
# 输出示例：1.x.y

# 查看你正在使用的 `oven-sh/bun` 的精确提交版本
bun --revision
# 输出示例：1.x.y+b7982ac13189
```

<Warning>
  如果你已安装 Bun，但出现 `command not found` 错误，可能需要手动将安装目录（`~/.bun/bin`）添加到你的 `PATH` 中。
</Warning>

<Accordion title="将 Bun 添加到你的 PATH">
  <Tabs>
    <Tab title="macOS & Linux">
      <Steps>
        <Step title="确认你使用的是哪个 shell">
          ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
          echo $SHELL
          # 可能输出：/bin/zsh 或 /bin/bash 或 /bin/fish
          ```
        </Step>

        <Step title="打开你的 shell 配置文件">
          * bash 使用：`~/.bashrc`
          * zsh 使用：`~/.zshrc`
          * fish 使用：`~/.config/fish/config.fish`
        </Step>

        <Step title="将 Bun 目录添加到 PATH">
          在配置文件中添加以下内容：

          ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
          export BUN_INSTALL="$HOME/.bun"
          export PATH="$BUN_INSTALL/bin:$PATH"
          ```
        </Step>

        <Step title="重新加载你的 shell 配置">
          ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
          source ~/.bashrc  # 或者 ~/.zshrc
          ```
        </Step>
      </Steps>
    </Tab>

    <Tab title="Windows">
      <Steps>
        <Step title="确认 bun 可执行文件是否正确安装">
          ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
          & "$env:USERPROFILE\.bun\bin\bun" --version
          ```

          如果该命令运行成功，但 `bun --version` 无法识别，说明 bun 未添加到系统 PATH。解决方法是打开 PowerShell 窗口，并运行以下命令：

          ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
          [System.Environment]::SetEnvironmentVariable(
            "Path",
            [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin",
            [System.EnvironmentVariableTarget]::User
          )
          ```
        </Step>

        <Step title="重启你的终端">
          运行命令后，重启终端并测试 `bun --version`

          ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
          bun --version
          ```
        </Step>
      </Steps>
    </Tab>
  </Tabs>
</Accordion>

***

## 升级

安装完成后，二进制文件可自动升级：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun upgrade
```

<Tip>
  **Homebrew 用户** <br />
  为避免与 Homebrew 冲突，请改用命令 `brew upgrade bun`。

  **Scoop 用户** <br />
  为避免与 Scoop 冲突，请改用命令 `scoop update bun`。
</Tip>

***

## Canary 版本

[-> 查看 Canary 版本](https://github.com/oven-sh/bun/releases/tag/canary)

Bun 会在每次主分支提交时自动发布（未经测试的）Canary 版本。要升级到最新 Canary 版本：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 升级到最新 Canary
bun upgrade --canary

# 切换回稳定版本
bun upgrade --stable
```

Canary 版本适用于测试新功能和修复 bug，帮助 Bun 团队更快修复问题。Canary 版本会自动上传崩溃报告给 Bun 团队。

***

## 安装旧版本

由于 Bun 是单一的二进制文件，你可以通过重新运行安装脚本并指定版本安装旧版本。

<Tabs>
  <Tab title="Linux & macOS">
    要安装指定版本，传入 git 标签给安装脚本：

    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    curl -fsSL https://bun.com/install | bash -s "bun-v1.3.3"
    ```
  </Tab>

  <Tab title="Windows">
    在 Windows 上，将版本号传入 PowerShell 安装脚本：

    ```powershell PowerShell icon="windows" theme={"theme":{"light":"github-light","dark":"dracula"}}
    iex "& {$(irm https://bun.com/install.ps1)} -Version 1.3.3"
    ```
  </Tab>
</Tabs>

***

## 直接下载

要直接下载 Bun 二进制文件，请访问 [GitHub 发布页面](https://github.com/oven-sh/bun/releases)。

### 最新版本下载

<CardGroup cols={2}>
  <Card icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/linux.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=bdaae2e86a822655a18a00e5fe613598" title="Linux x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip" width="216" height="256" data-path="icons/linux.svg">
    标准 Linux x64 二进制
  </Card>

  <Card icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/linux.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=bdaae2e86a822655a18a00e5fe613598" title="Linux x64 Baseline" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-baseline.zip" width="216" height="256" data-path="icons/linux.svg">
    适用于不支持 AVX2 的旧 CPU
  </Card>

  <Card icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/windows.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e08f75953045f102bd8baf57af10c90d" title="Windows x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64.zip" width="88" height="88" data-path="icons/windows.svg">
    标准 Windows 二进制
  </Card>

  <Card icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/windows.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e08f75953045f102bd8baf57af10c90d" title="Windows x64 Baseline" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64-baseline.zip" width="88" height="88" data-path="icons/windows.svg">
    适用于不支持 AVX2 的旧 CPU
  </Card>

  <Card icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/windows.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e08f75953045f102bd8baf57af10c90d" title="Windows ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-aarch64.zip" width="88" height="88" data-path="icons/windows.svg">
    适用于 ARM 架构（如骁龙等）的 Windows
  </Card>

  <Card icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/apple.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=8c359f076a7269ee80f41d300fb92b77" title="macOS ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-aarch64.zip" width="842" height="1000" data-path="icons/apple.svg">
    Apple Silicon (M1/M2/M3)
  </Card>

  <Card icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/apple.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=8c359f076a7269ee80f41d300fb92b77" title="macOS x64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-darwin-x64.zip" width="842" height="1000" data-path="icons/apple.svg">
    Intel Mac
  </Card>

  <Card icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/linux.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=bdaae2e86a822655a18a00e5fe613598" title="Linux ARM64" href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64.zip" width="216" height="256" data-path="icons/linux.svg">
    ARM64 Linux 系统
  </Card>
</CardGroup>

### Musl 二进制

适用于不支持 `glibc` 的发行版（如 Alpine Linux, Void Linux）：

* [Linux x64 musl](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-musl.zip)
* [Linux x64 musl baseline](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-musl-baseline.zip)
* [Linux ARM64 musl](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64-musl.zip)

<Note>
  Bun 的 glibc 二进制需要 glibc 2.17 或更高版本。如果你遇到类似 `bun:
      /lib/x86_64-linux-gnu/libc.so.6: version GLIBC_... not found` 的错误，请尝试使用 musl 二进制。Bun 的安装脚本会自动为你的系统选择正确的二进制。
</Note>

***

## CPU 要求

Bun 根据你使用的二进制文件对 CPU 有不同的要求：

<Tabs>
  <Tab title="标准版本">
    **x64 二进制** 目标为 Haswell CPU 架构（需要 AVX 和 AVX2 指令集）

    | 平台  | Intel 要求             | AMD 要求        |
    | --- | -------------------- | ------------- |
    | x64 | Haswell（第四代 Core）及更新 | Excavator 及更新 |
  </Tab>

  <Tab title="Baseline 版本">
    **x64-baseline 二进制** 目标为 Nehalem 架构，用于较老的 CPU

    | 平台           | Intel 要求             | AMD 要求        |
    | ------------ | -------------------- | ------------- |
    | x64-baseline | Nehalem（第一代 Core）及更新 | Bulldozer 及更新 |

    <Warning>
      Baseline 版本运行速度较慢，仅在遇到 “Illegal Instruction” 错误时使用。
    </Warning>
  </Tab>
</Tabs>

<Note>Bun 不支持低于 baseline 目标的 CPU，该目标要求支持 SSE4.2 指令集。macOS 也要求版本为 13.0 或更高。</Note>

***

## 卸载

要从系统中移除 Bun：

<Tabs>
  <Tab title="macOS & Linux">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    rm -rf ~/.bun
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell PowerShell icon="windows" theme={"theme":{"light":"github-light","dark":"dracula"}}
    powershell -c ~\.bun\uninstall.ps1
    ```
  </Tab>

  <Tab title="包管理器">
    <CodeGroup>
      ```bash npm icon="npm" theme={"theme":{"light":"github-light","dark":"dracula"}}
      npm uninstall -g bun
      ```

      ```bash Homebrew icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/homebrew.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=41bb4552d95e0853b4d6a2f9aa3906ab" theme={"theme":{"light":"github-light","dark":"dracula"}}
      brew uninstall bun
      ```

      ```bash Scoop icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
      scoop uninstall bun
      ```
    </CodeGroup>
  </Tab>
</Tabs>