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

# bun add

> 使用 Bun 的快速包管理器将包添加到你的项目

要添加特定包：

```bash terminal icon="terminal" theme={null}
bun add preact
```

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

```bash terminal icon="terminal" theme={null}
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={null}
bun add --dev @types/react
bun add -d @types/react
```

## `--optional`

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

```bash terminal icon="terminal" theme={null}
bun add --optional lodash
```

## `--peer`

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

```bash terminal icon="terminal" theme={null}
bun add --peer @types/bun
```

## `--exact`

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

要将包固定到已解析的版本，请使用 `--exact`。Bun 会将精确版本号写入 `package.json`，而不是版本范围。

```bash terminal icon="terminal" theme={null}
bun add react --exact
bun add react -E
```

`package.json` 中的区别：

```json package.json icon="file-json" theme={null}
{
  "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={null}
bun add --help
```

## `--global`

<Note>**别名** — `bun add --global`、`bun add -g`、`bun install --global` 和 `bun install -g`</Note>

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

```bash terminal icon="terminal" theme={null}
bun add --global cowsay # 或 `bun add -g cowsay`
cowsay "Bun!"
```

```txt theme={null}
 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
```

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

  # 全局安装的包 bin 被链接到的位置
  globalBinDir = "~/.bun/bin"
  ```
</Accordion>

## 可信依赖

与其他 npm 客户端不同，Bun 不会为已安装的依赖执行任意生命周期脚本，例如 `postinstall`。这些脚本代表潜在的安全风险，因为它们可以在你的机器上执行任意代码。

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

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

Bun 会读取此字段并为 `my-trusted-package` 运行生命周期脚本。

## Git 依赖

从公共或私有 git 仓库添加依赖：

```bash terminal icon="terminal" theme={null}
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={null}
{
  "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={null}
bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz
```

`bun add` 将 URL 写入你的 `package.json`：

```json package.json icon="file-json" theme={null}
{
  "dependencies": {
    "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
  }
}
```

***

## CLI 用法

```bash theme={null}
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>

### 项目文件与 Lockfile

<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> 或不保存 lockfile
</ParamField>

<ParamField path="--save" type="boolean" default="true">
  保存到 <code>package.json</code>
</ParamField>

<ParamField path="--frozen-lockfile" type="boolean">
  禁止更改 lockfile
</ParamField>

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

<ParamField path="--save-text-lockfile" type="boolean">
  保存基于文本的 lockfile
</ParamField>

<ParamField path="--lockfile-only" type="boolean">
  仅生成 lockfile，不安装依赖
</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">
  最大并发网络请求数
</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">
  生命周期脚本的最大并发作业数（默认：2 倍 CPU 核心数）
</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>