安装 Bun

2.1 安装前：先确认系统与 CPU 是否满足要求

Bun 以单个无外部依赖的可执行文件发布，安装的本质就是”下载一个二进制文件并放进 PATH”。但它对系统和 CPU 有最低要求，装之前先对一眼，可以省掉大量排查时间。

操作系统要求：

平台	最低要求	备注
macOS	macOS 13.0 或更高	支持 Apple Silicon（arm64）与 Intel（x64）
Linux	内核 3.10（RHEL 7）起可运行，推荐 5.6+	需要预装 unzip；旧内核会降级掉部分新系统调用
Windows	Windows 10 版本 1809 或更高	支持 x64 与 ARM64

CPU 要求：

• 标准构建（x64） 面向 Haswell 架构，需要 CPU 支持 AVX 与 AVX2 指令集。对应 Intel 第 4 代酷睿及以上、AMD Excavator 及以上。
• baseline 构建（x64-baseline） 面向更老的 Nehalem 架构，对应 Intel 第 1 代酷睿及以上、AMD Bulldozer 及以上。它比标准构建慢，只在遇到 “Illegal Instruction” 报错时才用。
• 再老的 CPU（不支持 SSE4.2）不被支持。

2.2 官方安装脚本（推荐）

这是覆盖面最广、最不容易出问题的方式。

macOS 与 Linux：

curl -fsSL https://bun.sh/install | bash

Windows（PowerShell）：

powershell -c "irm bun.sh/install.ps1 | iex"

脚本会自动判断当前平台与 CPU 特性，选择合适的二进制（包括在无 glibc 的发行版上自动选 musl 版本），默认安装到 ~/.bun，可执行文件位于 ~/.bun/bin/bun。

2.3 通过包管理器安装

如果你的机器已经在用某个系统级包管理器，用它安装可以让 Bun 跟其他工具一起被统一升级。

# npm（跨平台，需要已有 Node.js）
npm install -g bun

# Homebrew（macOS / Linux）
brew install oven-sh/bun/bun

# Scoop（Windows）
scoop install bun

Windows 上还可以用 winget 安装。官方文档没有列出这条途径，但 winget 官方仓库中有由 Bun 团队维护的清单，包 ID 为 Oven-sh.Bun：

winget install -e --id Oven-sh.Bun

# 老 CPU（不支持 AVX2）使用 baseline 变体
winget install -e --id Oven-sh.Bun.Baseline

混装冲突提醒：不要同时用两种方式安装 Bun。例如既跑了官方脚本又执行了 brew install，which bun（Windows 上 where bun）会告诉你实际生效的是哪一个，升级时也容易只升到其中一份。

2.4 Docker 镜像

官方提供了同时支持 Linux x64 与 arm64 的镜像：

docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

还有基于不同基础系统的变体，按体积与依赖需求选择：

docker pull oven/bun:debian
docker pull oven/bun:slim
docker pull oven/bun:distroless
docker pull oven/bun:alpine

一个最小可用的 Dockerfile 片段：

FROM oven/bun:slim
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
CMD ["bun", "run", "index.ts"]

2.5 验证安装

打开一个新的终端窗口（重要：旧窗口的 PATH 还是安装前的），执行：

bun --version
# 简写：bun -v

1.3.14

想知道精确到 commit 的版本，用 --revision：

bun --revision

1.3.14+b7982ac13189

在脚本里也可以从运行时读到版本号：

console.log(Bun.version);   // "1.3.14"
console.log(Bun.revision);  // "1.3.14+b7982ac13189"

2.6 排查 command not found：配置 PATH

装完却提示 bun: command not found，几乎都是 PATH 没生效。

macOS / Linux：

先确认自己用的是哪个 shell：

echo $SHELL
# /bin/zsh 或 /bin/bash 或 /bin/fish

然后在对应的配置文件（bash 是 ~/.bashrc，zsh 是 ~/.zshrc，fish 是 ~/.config/fish/config.fish）里追加：

export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

重新加载配置：

source ~/.bashrc   # 或 ~/.zshrc

Windows：

先确认二进制本身是否存在：

& "$env:USERPROFILE\.bun\bin\bun" --version

如果这条能跑通、而 bun --version 不行，说明只是 PATH 缺失。在 PowerShell 中执行：

[System.Environment]::SetEnvironmentVariable(
  "Path",
  [System.Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.bun\bin",
  [System.EnvironmentVariableTarget]::User
)

然后重启终端再验证。

2.7 升级与版本切换

常规升级

Bun 的二进制可以自我升级：

bun upgrade

canary 构建

Bun 对 main 分支的每次提交都会自动发布一个未经完整测试的 canary 构建，适合提前验证新特性或确认某个 bug 是否已修复：

# 升级到最新 canary
bun upgrade --canary

# 切回稳定版
bun upgrade --stable

安装指定旧版本

因为 Bun 就是一个二进制文件，安装旧版本只需要带上版本参数重跑安装脚本。这在需要复现某个版本的行为、或临时规避回归问题时很有用：

# Linux / macOS：传入 git tag
curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.3"

# Windows：传入版本号
iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.3.3"

也可以直接去 GitHub Releases 页面下载对应平台的压缩包（bun-linux-x64.zip、bun-darwin-aarch64.zip、bun-windows-x64.zip 等），其中带 -baseline 后缀的是面向老 CPU 的构建，带 -musl 后缀的是面向 Alpine、Void Linux 这类无 glibc 发行版的构建。

2.8 卸载

# macOS / Linux
rm -rf ~/.bun

# Windows
powershell -c ~\.bun\uninstall.ps1

用包管理器装的，用对应的卸载命令：

npm uninstall -g bun
brew uninstall bun
scoop uninstall bun

卸载后记得把之前手工加进 shell 配置文件的 BUN_INSTALL / PATH 两行删掉。

2.9 在 CI 中安装 Bun

GitHub Actions

官方提供了 oven-sh/setup-bun Action：

name: my-workflow
jobs:
  my-job:
    name: my-job
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2

      # 之后可以跑任意 bun / bunx 命令
      - run: bun install
      - run: bun run build
      - run: bun test

需要锁定版本时（CI 里强烈建议锁定，避免上游发版导致流水线行为漂移）：

      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.3.14   # 也可以填 "latest"、"canary" 或某个 commit sha

其他 CI 平台

没有官方 Action 的平台（GitLab CI、Jenkins、自建 Runner 等），有两条通用路子：

# 方式一：直接跑安装脚本（记得锁版本）
curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.14"
export PATH="$HOME/.bun/bin:$PATH"

# 方式二：直接用官方镜像做 job 容器（GitLab CI 示例）
build:
  image: oven/bun:1.3.14
  script:
    - bun install --frozen-lockfile
    - bun test

2.10 内网镜像与代理

这里要区分两件容易混淆的事：下载 Bun 本体和用 Bun 安装 npm 依赖，它们走的是不同的通道。

配置 npm 依赖的 registry

bun install 默认从 https://registry.npmjs.org/ 拉包。改成企业内网源或公共镜像，在 bunfig.toml 里配置：

[install]
registry = "https://registry.npmmirror.com"

需要鉴权时可以带 token 或用户名密码，并且支持通过 $变量名 引用环境变量，避免把凭据写死在仓库里：

[install]
registry = { url = "https://registry.example.com", token = "$NPM_TOKEN" }

只想给某个 scope 换源，用 install.scopes：

[install.scopes]
myorg = { token = "$NPM_TOKEN", url = "https://registry.example.com/" }

放在项目根目录的 bunfig.toml 只对当前项目生效；想全局生效，把文件放到 $HOME/.bunfig.toml 或 $XDG_CONFIG_HOME/.bunfig.toml（Windows 上即用户目录下的 .bunfig.toml）。两者同时存在时会做浅合并，项目级覆盖全局级。

配置 HTTP 代理

Bun 的网络请求（包括 fetch）遵循标准的代理环境变量：

HTTPS_PROXY=http://proxy.example.com:8080 bun install

带认证信息的写法：

export HTTPS_PROXY="https://username:password@proxy.example.com:8080"
export HTTP_PROXY="http://proxy.example.com:8080"
bun run index.ts

自定义 CA 证书

内网做了 HTTPS 中间人拦截时，需要把企业根证书告诉 Bun：

[install]
# 直接写证书内容
ca = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# 或指定证书文件路径（文件里可以包含多张证书）
cafile = "path/to/cafile"

2.11 小结与常见问题

小结：

• 首选官方脚本安装；已有包管理器习惯的用 brew / scoop / winget / npm；容器场景直接用 oven/bun 镜像。
• bun --version（或 bun -v）验证，bun --revision 看精确构建；装完记得开新终端。
• 升级用 bun upgrade，但包管理器安装的要用对应的包管理器升级命令。
• CI 里锁版本 + --frozen-lockfile；内网环境分别配置 registry、代理和 CA 证书。

常见问题速查：

现象	原因与处理
bun: command not found	PATH 未包含 ~/.bun/bin，见 2.6；或终端未重启
Illegal Instruction	CPU 不支持 AVX2，改用 baseline 构建
version GLIBC_... not found	glibc 版本过低，改用 musl 构建
Linux 上安装脚本失败	缺少 unzip，先 sudo apt install unzip
bun upgrade 后版本没变	实际生效的是包管理器安装的那一份，用 which bun 确认后改用对应升级命令
依赖下载很慢或超时	配置 [install] registry 换源，或设置 HTTPS_PROXY

装好之后，下一章我们写第一个 Bun 程序，看看”直接运行 TypeScript”到底是什么体验。