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

# bunx

> 运行 npm 包

<Note>`bunx` 是 `bun x` 的别名。当你安装 `bun` 时，`bunx` 命令行工具会被自动安装。</Note>

使用 `bunx` 来自动安装并运行来自 `npm` 的包。它是 Bun 版本的 `npx` 或 `yarn dlx`。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bunx cowsay "Hello world!"
```

<Note>
  ⚡️ **速度** — 利用 Bun 的快速启动时间，`bunx` 在运行本地安装的包时比 `npx` [快大约 100 倍](https://twitter.com/jarredsumner/status/1606163655527059458)。
</Note>

包可以在它们的 `package.json` 文件中的 `"bin"` 字段声明可执行文件。这些被称为 *包可执行文件* 或 *包二进制文件*。

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  // ... 其他字段
  "name": "my-cli",
  "bin": {
    "my-cli": "dist/index.js"
  }
}
```

这些可执行文件通常是带有 [shebang 行](https://en.wikipedia.org/wiki/Shebang_\(Unix\)) 的普通 JavaScript 文件，用来指示应该使用哪个程序来执行它们。下面的文件声明它应该用 `node` 来执行。

```js dist/index.js icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
#!/usr/bin/env node

console.log("Hello world!");
```

这些可执行文件可以通过 `bunx` 来运行，

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bunx my-cli
```

和 `npx` 一样，`bunx` 会先检查是否有本地安装的包，如果没有则会自动从 `npm` 安装。已安装的包会被存储到 Bun 的全局缓存中以供将来使用。

## 参数和标志

要向可执行文件传递额外的命令行标志和参数，请把它们放在可执行文件名之后。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bunx my-cli --foo bar
```

***

## Shebang 行

默认情况下，Bun 会尊重 shebang 行。如果一个可执行文件带有 `#!/usr/bin/env node`，Bun 会启动一个 `node` 进程来执行该文件。但有时我们希望即使文件指定了其它运行时，也使用 Bun 的运行时来执行。只需添加 `--bun` 标志即可。

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

`--bun` 标志必须 *出现在* 可执行文件名之前。位于可执行文件名 *之后* 的标志会传递给该可执行文件。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bunx --bun my-cli # 正确
bunx my-cli --bun # 错误
```

## Package 标志

**`--package <pkg>` 或 `-p <pkg>`** - 从指定包中运行二进制文件。当二进制文件名与包名不匹配时非常有用：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bunx -p renovate renovate-config-validator
bunx --package @angular/cli ng
```

要强制脚本总是使用 Bun 运行，使用 shebang：

```js dist/index.js icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
#!/usr/bin/env bun
```

***

## 使用方法

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bunx [flags] <package>[@version] [flags and arguments for the package]
```

执行 npm 包的可执行文件（CLI），如果在 `node_modules` 中未安装，则自动安装到全局共享缓存中。

### 参数

<ParamField path="--bun" type="boolean">
  强制命令使用 Bun 运行而非 Node.js，即使可执行文件包含 Node 的 shebang（`#!/usr/bin/env node`）
</ParamField>

<ParamField path="-p, --package" type="string">
  当二进制名称与包名不同时，指定要安装的包
</ParamField>

<ParamField path="--no-install" type="boolean">
  如果包尚未安装，则跳过安装
</ParamField>

<ParamField path="--verbose" type="boolean">
  安装过程中启用详细输出
</ParamField>

<ParamField path="--silent" type="boolean">
  安装过程中抑制输出
</ParamField>

### 示例

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 运行 Prisma 迁移
bunx prisma migrate

# 使用 Prettier 格式化文件
bunx prettier foo.js

# 运行指定版本的包
bunx uglify-js@3.14.0 app.js

# 当二进制名称与包名不同时，使用 --package 指定包
bunx -p @angular/cli ng new my-app

# 强制使用 Bun 运行而非 Node.js，即使可执行文件包含 Node shebang
bunx --bun vite dev foo.js
```