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

> 使用 Bun 的快速包管理器安装包

## 基本用法

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun install react
bun install react@19.1.1 # 指定版本
bun install react@latest # 指定标签
```

`bun` CLI 包含一个兼容 Node.js 的包管理器，旨在极大地加速替代 `npm`、`yarn` 和 `pnpm`。它是一个独立工具，可以在已有的 Node.js 项目中工作；如果你的项目中有 `package.json`，`bun install` 能帮你提升工作流程速度。

<Note>
  **⚡️ 速度提升 25 倍** — 在任何 Node.js 项目中从 `npm install` 切换到 `bun install`，安装速度可提升高达 25 倍。

  <Frame>
    ![Bun 安装速度对比](https://user-images.githubusercontent.com/709451/147004342-571b6123-17a9-49a2-8bfd-dcfc5204047e.png)
  </Frame>
</Note>

<Accordion title="针对 Linux 用户">
  建议使用的最低 Linux 内核版本是 5.6。如果你使用的是 Linux 内核 5.1 到 5.5，`bun install` 能工作，但 HTTP 请求会较慢，因为缺少对 io\_uring 的 `connect()` 操作支持。

  如果你使用的是 Ubuntu 20.04，可以通过以下方式安装[新版内核](https://wiki.ubuntu.com/Kernel/LTSEnablementStack):

  ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
  # 如果返回版本号 >= 5.6，则无需操作
  uname -r

  # 安装 Ubuntu 官方硬件支持内核
  sudo apt install --install-recommends linux-generic-hwe-20.04
  ```
</Accordion>

安装项目中所有依赖：

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

执行 `bun install` 时会：

* **安装** 所有 `dependencies`、`devDependencies` 与 `optionalDependencies`。Bun 默认也会安装 `peerDependencies`。
* **运行** 项目的 `{pre|post}install` 和 `{pre|post}prepare` 脚本，且在合适的时机执行。出于安全考虑，Bun **不会执行** 已安装依赖的生命周期脚本。
* **写入** 一个 `bun.lock` 锁文件到项目根目录。

***

## 日志记录

调整日志详情级别：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun install --verbose # 调试日志
bun install --silent  # 静默无日志
```

***

## 生命周期脚本

与其他 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` 运行生命周期脚本。

生命周期脚本安装时并行运行。调整最大并行脚本数量使用 `--concurrent-scripts` 参数。默认值为报告的 CPU 核心数或 GOMAXPROCS 的两倍。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun install --concurrent-scripts 5
```

Bun 会自动优化知名包（如 `esbuild`、`sharp` 等）的 postinstall 脚本，确定必需运行的脚本。若想关闭此优化：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install
```

***

## 工作区（Workspaces）

Bun 支持 `package.json` 中的 `"workspaces"`。完整文档请参考 [包管理器 > 工作区](/pm/workspaces)。

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "name": "my-app",
  "version": "1.0.0",
  "workspaces": ["packages/*"], // [!code ++]
  "dependencies": {
    "preact": "^10.5.13"
  }
}
```

***

## 为特定包安装依赖

在 monorepo 中，可以通过 `--filter` 参数针对部分包安装依赖。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 为除了 `pkg-c` 之外的所有工作区安装依赖
bun install --filter '!pkg-c'

# 仅为 `./packages/pkg-a` 中的 `pkg-a` 安装依赖
bun install --filter './packages/pkg-a'
```

有关 `bun install` 过滤的详细信息，请参阅 [包管理器 > 过滤](/pm/filter#bun-install-and-bun-outdated)。

***

## 覆盖与解析

Bun 支持 `package.json` 中 npm 的 `"overrides"` 和 Yarn 的 `"resolutions"`。它们允许针对依赖的依赖（半依赖）指定版本范围。完整文档参见 [包管理器 > 覆盖和解析](/pm/overrides)。

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": { // [!code ++]
    "bar": "~4.4.0" // [!code ++]
  } // [!code ++]
}
```

***

## 全局安装包

使用 `-g` 或 `--global` 参数进行全局安装。通常用于安装命令行工具。

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

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

***

## 生产模式

以生产模式安装（不含 `devDependencies` 与 `optionalDependencies`）：

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

为实现可复现安装，请使用 `--frozen-lockfile`。此时将安装 `bun.lock` 指定的确切版本。如果你的 `package.json` 与 `bun.lock` 不一致，Bun 会报错退出，且不会更新锁文件。

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

更多关于 `bun.lock` 锁文件内容，见 [包管理器 > 锁文件](/pm/lockfile)。

***

## 省略依赖

用 `--omit` 标记省略 dev、peer 或 optional 依赖。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 从安装中排除 "devDependencies"。同时适用于根包和工作区（若存在）。传递依赖不会拥有 devDependencies。
bun install --omit dev

# 仅安装 "dependencies"
bun install --omit=dev --omit=peer --omit=optional
```

***

## 演练模式

执行演练（不实际安装任何东西）：

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

***

## 非 npm 依赖

Bun 支持从 Git、GitHub 和本地或远程 tar 包安装依赖。完整文档见 [包管理器 > Git、GitHub 和 tarball 依赖](/pm/cli/add)。

```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",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}
```

***

## 安装策略

Bun 支持两种包安装策略，决定依赖如何组织在 `node_modules` 中：

### 扁平安装（Hoisted installs）

传统 npm/Yarn 方式，将依赖扁平化合并到共享的 `node_modules` 目录：

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

### 隔离安装（Isolated installs）

类似 pnpm 的方式，创建严格的依赖隔离，防止幻影依赖：

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

隔离安装会在 `node_modules/.bun/` 创建中央包存储，并在顶层 `node_modules` 中使用符号链接，确保包只能访问声明的依赖。

### 默认策略

默认链接器策略依据是否是新项目或已有项目：

* **新工作区/monorepo**：`isolated`（防止幻影依赖）
* **新单包项目**：`hoisted`（传统 npm 行为）
* **旧项目（v1.3.2 之前创建）**：`hoisted`（保留向后兼容）

默认由锁文件中的 `configVersion` 字段控制。详情见 [包管理器 > 隔离安装](/pm/isolated-installs)。

***

## 最小发布年龄

为防止供应链攻击（恶意包快速发布），可以配置 npm 包的最小发布时间。发布早于此阈值（秒）的版本才会被允许安装。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 只安装至少三天前发布的版本
bun add @types/bun --minimum-release-age 259200 # 秒
```

也可以在 `bunfig.toml` 配置：

```toml bunfig.toml icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]
# 最低发布时间为三天
minimumReleaseAge = 259200 # 秒

# 排除信任包绕过年龄检测
minimumReleaseAgeExcludes = ["@types/node", "typescript"]
```

启用最小年龄过滤时：

* 只影响新包版本解析 - 已有 `bun.lock` 中的包不变
* 解析时所有依赖（直接及传递）均经过年龄过滤
* 被过滤的版本触发稳定性检测，防止快速发布的无效版本被安装
  * 若发现多版本间隔接近年龄门限，会延长过滤期，选择更稳定更旧版本
  * 搜索时间最长为 7 天，若仍快速发布则跳过稳定性检测
  * 精确版本请求（如 `package@1.1.1`）仍受年龄限制但绕过稳定性检测
* 无 `time` 字段视为通过年龄检测（npm registry 通常总有时间戳）

更高级的安全扫描、集成服务与自定义过滤，见 [包管理器 > 安全扫描器 API](/pm/security-scanner-api)。

***

## 配置

### 通过 `bunfig.toml` 配置 `bun install`

`bunfig.toml` 会在 `bun install`、`bun remove` 和 `bun add` 时搜索：

1. `$XDG_CONFIG_HOME/.bunfig.toml` 或 `$HOME/.bunfig.toml`
2. 当前目录下的 `./bunfig.toml`

二者均存在时结果合并。

使用 `bunfig.toml` 配置为可选。Bun 力图零配置但非所有功能无配置可用。`bun install` 默认行为可在此配置，以下为默认值。

```toml bunfig.toml icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[install]

# 是否安装 optionalDependencies
optional = true

# 是否安装 devDependencies
dev = true

# 是否安装 peerDependencies
peer = true

# 等同于 `--production`
production = false

# 等同于 `--save-text-lockfile`
saveTextLockfile = false

# 等同于 `--frozen-lockfile`
frozenLockfile = false

# 等同于 `--dry-run`
dryRun = false

# 等同于 `--concurrent-scripts`
concurrentScripts = 16 # (cpu 核心数或 GOMAXPROCS) x2

# 安装策略："hoisted" 或 "isolated"
# 默认依赖于锁文件 configVersion 和是否使用工作区：
# - configVersion = 1: 若使用工作区则 "isolated"，否则 "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"

# 最小发布时间配置
minimumReleaseAge = 259200 # 秒
minimumReleaseAgeExcludes = ["@types/node", "typescript"]
```

### 通过环境变量配置

环境变量优先级高于 `bunfig.toml`。

| 名称                                 | 描述                                                                      |
| ---------------------------------- | ----------------------------------------------------------------------- |
| `BUN_CONFIG_REGISTRY`              | 设置 npm 仓库（默认：[https://registry.npmjs.org）](https://registry.npmjs.org）) |
| `BUN_CONFIG_TOKEN`                 | 设置授权令牌（当前无实际功能）                                                         |
| `BUN_CONFIG_YARN_LOCKFILE`         | 保存 Yarn v1 风格的 yarn.lock                                                |
| `BUN_CONFIG_LINK_NATIVE_BINS`      | 指向 platform-specific 的 `bin` 依赖                                         |
| `BUN_CONFIG_SKIP_SAVE_LOCKFILE`    | 不保存锁文件                                                                  |
| `BUN_CONFIG_SKIP_LOAD_LOCKFILE`    | 不读取锁文件                                                                  |
| `BUN_CONFIG_SKIP_INSTALL_PACKAGES` | 不安装任何包                                                                  |

Bun 在 macOS 默认使用 `clonefile`，在 Linux 默认使用 `hardlink` 安装方法，这样性能最佳。可用 `--backend` 参数切换安装后端。不可用或错误时，`clonefile` 和 `hardlink` 会降级使用平台特定复制实现。

Bun 将从 npm 下载的包缓存至 `~/.bun/install/cache/${name}@${version}`。若 semver 版本包含 `build` 或 `pre` 标签，则用该值哈希替代。此举可减少路径过长导致的错误，但可能使查找包安装路径更复杂。

当 `node_modules` 存在时，Bun 会检查 `node_modules/package/package.json` 中的 `"name"` 和 `"version"` 是否符合预期来决定是否安装。它使用自定义 JSON 解析，一旦读取这两个字段即停止。

若无 `bun.lock` 或 `package.json` 依赖变更，Bun 会在解析时主动下载并解压 tar 包。

存在 `bun.lock` 且 `package.json` 未变时，Bun 懒加载缺失依赖。若期望位置已有匹配的包，Bun 将不下载 tar 包。

## CI/CD

在 GitHub Actions 中使用官方 [`oven-sh/setup-bun`](https://github.com/oven-sh/setup-bun) 动作安装 Bun：

```yaml .github/workflows/release.yml icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}}
name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Build app
        run: bun run build
```

对要求可复现构建的 CI/CD 环境，可用 `bun ci` 确保 `package.json` 与锁文件同步，不符时构建失败：

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

等价于 `bun install --frozen-lockfile`，从锁文件安装精确版本，且 `package.json` 不匹配时失败。使用 `bun ci` 或 `bun install --frozen-lockfile` 必须版本控制中提交 `bun.lock`。

使用时将 `bun install` 替换为 `bun ci`。

```yaml .github/workflows/release.yml icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}}
name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun ci
      - name: Build app
        run: bun run build
```

## 平台特定依赖？

Bun 在锁文件中存储来自 npm 的 normalized `cpu` 和 `os` 值及解析的包。针对当前运行时禁用的包，跳过下载、解压和安装。这意味着不同平台/架构安装的包会不同，但锁文件保持一致。

### `--cpu` 和 `--os` 参数

你可以覆盖目标平台进行包选择：

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bun install --cpu=x64 --os=linux
```

安装指定平台的包，方便跨平台构建或准备不同环境部署。

**可用 `--cpu` 值**：`arm64`、`x64`、`ia32`、`ppc64`、`s390x`

**可用 `--os` 值**：`linux`、`darwin`、`win32`、`freebsd`、`openbsd`、`sunos`、`aix`

## Peer 依赖？

Peer 依赖处理与 yarn 类似。`bun install` 会自动安装 peer 依赖。如 `peerDependenciesMeta` 中标记为可选，且已有依赖可用，会优先使用已有依赖。

## 锁文件

`bun.lock` 是 Bun 的锁文件格式。详见 [关于文本锁文件的博客](https://bun.com/blog/bun-lock-text-lockfile)。

Bun 1.2 之前使用二进制锁文件 `bun.lockb`。可通过运行 `bun install --save-text-lockfile --frozen-lockfile --lockfile-only` 升级旧锁文件为新格式，然后删除 `bun.lockb`。

## 缓存

删除缓存：

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm cache rm
# 或
rm -rf ~/.bun/install/cache
```

## 平台特定后端

`bun install` 根据平台调用不同系统调用安装依赖以优化性能。可用 `--backend` 强制指定。

**`hardlink`** 是 Linux 默认后端，基准测试显示其性能最佳。

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
rm -rf node_modules
bun install --backend hardlink
```

**`clonefile`** 是 macOS 默认后端，性能最好，仅 macOS 可用。

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
rm -rf node_modules
bun install --backend clonefile
```

**`clonefile_each_dir`** 类似 `clonefile`，但每个目录逐文件克隆。仅 macOS 可用，通常性能不及 `clonefile`。不支持一次系统调用递归克隆子目录。

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
rm -rf node_modules
bun install --backend clonefile_each_dir
```

**`copyfile`** 是所有后端失败时的回退方法，速度最慢。macOS 使用 `fcopyfile()`，Linux 使用 `copy_file_range()`。

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
rm -rf node_modules
bun install --backend copyfile
```

**`symlink`** 通常仅用于内部 `file:` 依赖（以及未来的 `link:`）。为防止循环链接，不会对 `node_modules` 文件夹做符号链接。

若用 `--backend=symlink` 安装，除非每个依赖都有自己的 `node_modules`，否则 Node.js 不会正确解析依赖的 `node_modules`，除非对 `node` 或 `bun` 使用 `--preserve-symlinks` 参数。详见 [Node.js 关于 `--preserve-symlinks` 文档](https://nodejs.org/api/cli.html#--preserve-symlinks)。

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
rm -rf node_modules
bun install --backend symlink
bun --preserve-symlinks ./my-file.js
node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks
```

## npm 注册表元数据

Bun 使用二进制格式缓存 npm 注册表响应，载入比 JSON 快且占用空间小。缓存位于 `~/.bun/install/cache/*.npm`，文件名为 `${hash(packageName)}.npm`。使用哈希避免为 scoped 包创建多层目录。

Bun 使用 `Cache-Control` 忽略 `Age` 以提升性能，可能导致缓存数据比 npm 注册表晚约 5 分钟。

## pnpm 迁移

当检测到 `pnpm-lock.yaml` 且无 `bun.lock` 时，Bun 会自动在安装时将 pnpm 锁文件迁移为 `bun.lock`。迁移不会修改原始 `pnpm-lock.yaml`。

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

**注意**：迁移仅在无 `bun.lock` 时执行，当前无禁止迁移的选项。

迁移内容：

### 锁文件迁移

* 将 `pnpm-lock.yaml` 转换成 `bun.lock` 格式
* 保留版本和解析信息
* 保持依赖关系及 peer 依赖
* 支持补丁依赖并含数据完整性哈希

### 工作区配置

检测到 `pnpm-workspace.yaml` 时，将工作区配置迁移至根 `package.json`：

```yaml pnpm-workspace.yaml icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}}
packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

catalogs:
  build:
    webpack: ^5.0.0
    babel: ^7.0.0
```

工作区包列表和目录将移至 `workspaces` 字段：

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0",
      "typescript": "^5.0.0"
    },
    "catalogs": {
      "build": {
        "webpack": "^5.0.0",
        "babel": "^7.0.0"
      }
    }
  }
}
```

### 目录依赖

支持 pnpm 的 `catalog:` 协议依赖保留：

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "dependencies": {
    "react": "catalog:",
    "webpack": "catalog:build"
  }
}
```

### 配置迁移

将 pnpm 配置从 `pnpm-lock.yaml` 和 `pnpm-workspace.yaml` 迁移至根部：

* **overrides** 从 `pnpm.overrides` 迁移至 `package.json` 根级 `overrides`
* **patchedDependencies** 从 `pnpm.patchedDependencies` 迁移至 `package.json` 根级 `patchedDependencies`
* **workspace overrides** 应用自 `pnpm-workspace.yaml` 至根 `package.json`

### 要求

* 需 pnpm 锁文件版本至少 7
* 工作区包需提供 `package.json` 的 `name` 字段
* 目录下所有 catalog 依赖必须在目录定义中存在

迁移完成后，可以安全删除 `pnpm-lock.yaml` 和 `pnpm-workspace.yaml`。

***

## CLI 用法

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun install <name>@<version>
```

### 通用配置

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

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

### 依赖范围与管理

<ParamField path="--production" type="boolean">
  不安装 devDependencies
</ParamField>

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

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

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

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

### 依赖类型与版本控制

<ParamField path="--dev" type="boolean">
  添加依赖到 "devDependencies"
</ParamField>

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

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

<ParamField path="--exact" type="boolean">
  添加确切版本，而非 ^ 范围版本
</ParamField>

### 锁文件控制

<ParamField path="--yarn" type="boolean">
  写入 yarn.lock 文件（yarn v1）
</ParamField>

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

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

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

### 网络与注册表设置

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

<ParamField path="--cafile" type="string">
  证书颁发机构签名证书的文件路径
</ParamField>

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

### 安装过程控制

<ParamField path="--dry-run" type="boolean">
  不执行任何安装操作
</ParamField>

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

<ParamField path="--global" type="boolean">
  全局安装
</ParamField>

<ParamField path="--backend" type="string" default="clonefile">
  平台特定优化选项："clonefile"、"hardlink"、"symlink"、"copyfile"
</ParamField>

<ParamField path="--filter" type="string">
  为匹配的工作区安装包
</ParamField>

<ParamField path="--analyze" type="boolean">
  递归分析并安装作为参数传入文件的所有依赖
</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="--no-verify" type="boolean">
  跳过新下载包的完整性验证
</ParamField>

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

### 并发与性能

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

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

### 生命周期脚本管理

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

### 帮助信息

<ParamField path="--help" type="boolean">
  打印此帮助菜单
</ParamField>