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

# bun add

> 使用 Bun 的快速包管理器向您的项目添加包

添加特定包：

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

指定版本、版本范围或标签：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add zod@3.20.0
bun add zod@^3.0.0
bun add zod@latest
```

## `--dev`

<Note>**别名** — `--development`，`-d`，`-D`</Note>

将包作为开发依赖（`"devDependencies"`）添加：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add --dev @types/react
bun add -d @types/react
```

## `--optional`

将包作为可选依赖（`"optionalDependencies"`）添加：

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

## `--peer`

将包作为对等依赖（`"peerDependencies"`）添加：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add --peer @types/bun
```

## `--exact`

<Note>**别名** — `-E`</Note>

使用 `--exact` 添加包并固定解析的版本。此操作将解析包的版本并以精确的版本号添加到您的 `package.json` 中，而非版本范围。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add react --exact
bun add react -E
```

这将在您的 `package.json` 中添加如下内容：

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "dependencies": {
    // 不使用 --exact
    "react": "^18.2.0", // 匹配 >= 18.2.0 < 19.0.0

    // 使用 --exact
    "react": "18.2.0" // 仅精确匹配 18.2.0 版本
  }
}
```

查看此命令的完整选项列表：

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

## `--global`

<Note>
  **注意** — 这不会修改当前项目文件夹的 package.json。**别名** - `bun add --global`，`bun add -g`，`bun install --global` 以及 `bun install -g`
</Note>

使用 `-g`/`--global` 标志全局安装包。这不会修改您当前项目的 `package.json`。通常用于安装命令行工具。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add --global cowsay # 或 `bun add -g cowsay`
cowsay "Bun!"
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
```

<Accordion title="配置全局安装行为">
  ```toml bunfig.toml icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
  [install]
  # `bun add --global` 安装包的位置
  globalDir = "~/.bun/install/global"

  # 全局安装的包二进制文件链接位置
  globalBinDir = "~/.bun/bin"
  ```
</Accordion>

## 受信任的依赖

与其它 npm 客户端不同，Bun 不会执行已安装依赖的任意生命周期脚本，如 `postinstall`。这些脚本存在安全风险，可能在您的机器上执行任意代码。

要让 Bun 允许特定包的生命周期脚本，请在您的 package.json 中将该包添加到 `trustedDependencies`。

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["my-trusted-package"] // [!code ++]
}
```

Bun 读取此字段，并允许 `my-trusted-package` 执行生命周期脚本。

## Git 依赖

添加来自公共或私有 Git 仓库的依赖：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add git@github.com:moment/moment.git
```

<Note>
  安装私有仓库时，系统需具备相应的 SSH 凭据以访问该仓库。
</Note>

Bun 支持多种协议，包括 [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls)、[`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies)、`git+ssh`、`git+https` 等。

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "git@github.com:moment/moment.git",
    "zod": "github:colinhacks/zod"
  }
}
```

## Tarball 依赖

包名可以对应公开托管的 `.tgz` 文件。安装时，Bun 将从指定的 tarball URL 下载并安装包，而非从包注册表。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz
```

这将在您的 `package.json` 中添加如下行：

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "dependencies": {
    "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
  }
}
```

***

## CLI 使用方法

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bun add <package> <@version>
```

### 依赖管理

<ParamField path="--production" type="boolean">
  不安装 devDependencies。别名：<code>-p</code>
</ParamField>

<ParamField path="--omit" type="string">
  安装时排除 <code>dev</code>、<code>optional</code> 或 <code>peer</code> 依赖
</ParamField>

<ParamField path="--global" type="boolean">
  全局安装。别名：<code>-g</code>
</ParamField>

<ParamField path="--dev" type="boolean">
  添加依赖到 <code>devDependencies</code>。别名：<code>-d</code>
</ParamField>

<ParamField path="--optional" type="boolean">
  添加依赖到 <code>optionalDependencies</code>
</ParamField>

<ParamField path="--peer" type="boolean">
  添加依赖到 <code>peerDependencies</code>
</ParamField>

<ParamField path="--exact" type="boolean">
  添加精确版本，而非 <code>^</code> 范围。别名：<code>-E</code>
</ParamField>

<ParamField path="--only-missing" type="boolean">
  仅在 <code>package.json</code> 中不存在该依赖时才添加
</ParamField>

### 项目文件与锁文件

<ParamField path="--yarn" type="boolean">
  生成 <code>yarn.lock</code> 文件（yarn v1）。别名：<code>-y</code>
</ParamField>

<ParamField path="--no-save" type="boolean">
  不更新 <code>package.json</code> 或保存锁文件
</ParamField>

<ParamField path="--save" type="boolean" default="true">
  保存至 <code>package.json</code>（默认开启）
</ParamField>

<ParamField path="--frozen-lockfile" type="boolean">
  不允许修改锁文件
</ParamField>

<ParamField path="--trust" type="boolean">
  将依赖添加到项目 <code>package.json</code> 的 <code>trustedDependencies</code> 并安装该包
</ParamField>

<ParamField path="--save-text-lockfile" type="boolean">
  保存为文本格式的锁文件
</ParamField>

<ParamField path="--lockfile-only" type="boolean">
  仅生成锁文件，不安装依赖
</ParamField>

### 安装控制

<ParamField path="--dry-run" type="boolean">
  不执行实际安装
</ParamField>

<ParamField path="--force" type="boolean">
  总是从注册表请求最新版本并重新安装所有依赖。别名：<code>-f</code>
</ParamField>

<ParamField path="--no-verify" type="boolean">
  跳过新下载包的完整性校验
</ParamField>

<ParamField path="--ignore-scripts" type="boolean">
  跳过项目 <code>package.json</code> 中的生命周期脚本（依赖的脚本永远不会执行）
</ParamField>

<ParamField path="--analyze" type="boolean">
  递归分析并安装作为参数传入文件的依赖（使用 Bun 的打包器）。别名：<code>-a</code>
</ParamField>

### 网络与注册表

<ParamField path="--ca" type="string">
  提供证书颁发机构签名证书
</ParamField>

<ParamField path="--cafile" type="string">
  与 <code>--ca</code> 相同，但通过证书文件路径提供
</ParamField>

<ParamField path="--registry" type="string">
  默认使用指定注册表，覆盖 <code>.npmrc</code>、<code>bunfig.toml</code> 和环境变量
</ParamField>

<ParamField path="--network-concurrency" type="number" default="48">
  最大并发网络请求数（默认 48）
</ParamField>

### 性能与资源

<ParamField path="--backend" type="string" default="clonefile">
  安装依赖的特定平台优化。可选值：<code>clonefile</code>（默认）、<code>hardlink</code>、<code>symlink</code>、<code>copyfile</code>
</ParamField>

<ParamField path="--concurrent-scripts" type="number" default="5">
  生命周期脚本的最大并发任务数（默认 5）
</ParamField>

### 缓存

<ParamField path="--cache-dir" type="string">
  从指定目录路径存储和加载缓存数据
</ParamField>

<ParamField path="--no-cache" type="boolean">
  完全忽略清单缓存
</ParamField>

### 输出与日志

<ParamField path="--silent" type="boolean">
  不输出任何日志
</ParamField>

<ParamField path="--verbose" type="boolean">
  输出超详细日志
</ParamField>

<ParamField path="--no-progress" type="boolean">
  关闭进度条
</ParamField>

<ParamField path="--no-summary" type="boolean">
  不打印总结信息
</ParamField>

### 全局配置与上下文

<ParamField path="--config" type="string">
  指定配置文件路径（<code>bunfig.toml</code>）。别名：<code>-c</code>
</ParamField>

<ParamField path="--cwd" type="string">
  设置当前工作目录
</ParamField>

### 帮助

<ParamField path="--help" type="boolean">
  显示此帮助菜单。别名：<code>-h</code>
</ParamField>