> ## 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 install 迁移到 bun install

`bun install` 是一个兼容 Node.js 的 npm 客户端，旨在成为极其快速的 npm 继任者。

要从 `npm install` 迁移到 `bun install`，请改用 `bun install`，不要再使用 `npm install`。

* **为 Node.js 和 Bun 设计**：`bun install` 会安装一个兼容 Node.js 的 `node_modules` 文件夹。你可以在 Node.js 项目中直接替代 `npm install` 使用，无需任何代码更改，也无需使用 Bun 的运行时。
* **自动将 `package-lock.json` 转换为 bun 的锁文件格式 `bun.lock`**，保留你现有解析的依赖版本，无需任何手动操作。你可以在公司偷偷用 `bun install` 替代 `npm install`，没人会发现。
* **兼容 `.npmrc`**：bun install 会读取 npm 的 `.npmrc` 里的 npm registry 配置，因此你可以为 npm 和 Bun 使用同样的配置。
* **硬链接**：在 Windows 和 Linux 上，`bun install` 使用硬链接以节省磁盘空间和缩短安装时间。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 迁移只需一条命令
bun i

# 添加依赖：
bun i @types/bun

# 添加开发依赖：
bun i -d @types/bun

# 移除依赖：
bun rm @types/bun
```

***

## 更快地运行 package.json 脚本

从 package.json 中运行脚本，从 `node_modules/.bin` 中运行可执行文件（有点像 `npx`），以及运行 JavaScript/TypeScript 文件（例如 `node`）——全部都由一条命令完成。

| NPM                | Bun              |
| ------------------ | ---------------- |
| `npm run <script>` | `bun <script>`   |
| `npm exec <bin>`   | `bun <bin>`      |
| `node <file>`      | `bun <file>`     |
| `npx <package>`    | `bunx <package>` |

当你使用 `bun run <executable>` 时，它会选择本地安装的可执行文件。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 运行 package.json 脚本：
bun my-script
bun run my-script

# 运行 node_modules/.bin 中的可执行程序：
bun my-executable # 例如 tsc，esbuild 等
bun run my-executable

# 运行一个 JavaScript/TypeScript 文件：
bun ./index.ts
```

***

## 支持工作区（Workspaces）

`bun install` 支持类似 npm 的工作区功能，并且提供更多特性。

在 package.json 中，你可以将 `"workspaces"` 设置为一组相对路径数组。

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "name": "my-app",
  "workspaces": ["packages/*", "apps/*"]
}
```

***

### 按工作区名称筛选脚本

在 Bun 中，`--filter` 标志支持通配符模式，会并行执行命令到所有 `name` 匹配该模式的工作区包，并遵循依赖顺序。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun --filter 'lib-*' my-script
# 替代以下写法：
# npm run --workspace lib-foo --workspace lib-bar my-script
```

***

## 更新依赖

要更新依赖，可以使用 `bun update <package>`。该命令会将依赖更新到符合 semver 范围的最新版本。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 更新单个依赖
bun update @types/bun

# 更新所有依赖
bun update

# 忽略 semver 范围，更新到最新版本
bun update @types/bun --latest

# 更新依赖到指定版本
bun update @types/bun@1.3.3

# 更新所有依赖到最新版本
bun update --latest
```

***

### 查看过期依赖

要查看过期依赖，运行 `bun outdated`。这类似于 `npm outdated`，但输出更为简洁。

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

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
┌────────────────────────────────────────┬─────────┬────────┬────────┐
│ Package                                │ Current │ Update │ Latest │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ @types/bun (dev)                       │ 1.1.6   │ 1.1.10 │ 1.1.10 │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ @types/react (dev)                     │ 18.3.3  │ 18.3.8 │ 18.3.8 │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ @typescript-eslint/eslint-plugin (dev) │ 7.16.1  │ 7.18.0 │ 8.6.0  │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ @typescript-eslint/parser (dev)        │ 7.16.1  │ 7.18.0 │ 8.6.0  │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ @vscode/debugadapter (dev)             │ 1.66.0  │ 1.67.0 │ 1.67.0 │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ esbuild (dev)                          │ 0.21.5  │ 0.21.5 │ 0.24.0 │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ eslint (dev)                           │ 9.7.0   │ 9.11.0 │ 9.11.0 │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ mitata (dev)                           │ 0.1.11  │ 0.1.14 │ 1.0.2  │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ prettier-plugin-organize-imports (dev) │ 4.0.0   │ 4.1.0  │ 4.1.0  │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ source-map-js (dev)                    │ 1.2.0   │ 1.2.1  │ 1.2.1  │
├────────────────────────────────────────┼─────────┼────────┼────────┤
│ typescript (dev)                       │ 5.5.3   │ 5.6.2  │ 5.6.2  │
└────────────────────────────────────────┴─────────┴────────┴────────┘
```

***

## 列出已安装的包

要列出已安装的包，可以使用 `bun pm ls`。这会列出 `node_modules` 文件夹中安装的所有包，bun 的锁文件作为事实依据。你可以传入 `-a` 标志来列出所有已安装的依赖，包括传递依赖。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 列出顶级已安装的包：
bun pm ls
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
my-pkg node_modules (781)
├── @types/node@20.16.5
├── @types/react@18.3.8
├── @types/react-dom@18.3.0
├── eslint@8.57.1
├── eslint-config-next@14.2.8
...
```

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 列出所有已安装的包：
bun pm ls -a
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
my-pkg node_modules
├── @alloc/quick-lru@5.2.0
├── @isaacs/cliui@8.0.2
│   └── strip-ansi@7.1.0
│       └── ansi-regex@6.1.0
├── @jridgewell/gen-mapping@0.3.5
├── @jridgewell/resolve-uri@3.1.2
...
```

***

## 创建包的压缩包

要创建包的 tar 压缩包，可以使用 `bun pm pack`。这会在当前目录创建一个包的 tarball。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 创建一个 tarball
bun pm pack
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
Total files: 46
Shasum: 2ee19b6f0c6b001358449ca0eadead703f326216
Integrity: sha512-ZV0lzWTEkGAMz[...]Gl4f8lA9sl97g==
Unpacked size: 0.41MB
Packed size: 117.50KB
```

***

## Shebang

如果包的 shebang 中引用了 `node`（例如 `#!/usr/bin/env node`），`bun run` 默认会尊重它并使用系统的 `node` 可执行文件。你也可以通过传递 `--bun` 参数强制使用 Bun 的 `node`。

当你传入 `--bun` 给 `bun run`，我们会在临时目录创建一个指向本地已安装 Bun 可执行文件的 `"node"` 符号链接，并在脚本执行期间将该目录添加到你的 `PATH`。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 强制使用 Bun 运行时而非 node
bun --bun my-script

# 以下用法同样有效：
bun run --bun my-script
```

***

## 全局安装

你可以使用 `bun i -g <package>` 全局安装包。默认情况下，这会安装到你用户主目录下的 `.bun/install/global/node_modules` 文件夹。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 全局安装一个包
bun i -g eslint

# 运行全局安装的包，无需 `bun run` 前缀
eslint --init
```