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

> 包管理器工具

`bun pm` 命令组是一组用于使用 Bun 包管理器的实用工具。

## pack

创建当前工作区的 tar 包：

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

`bun pm pack` 会创建一个包含所有将发布到 npm 的文件的 `.tgz` 文件，并遵循与 `npm pack` 相同的规则。

## 示例

基本用法：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm pack
# 在当前目录创建 my-package-1.0.0.tgz
```

脚本静默模式：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
TARBALL=$(bun pm pack --quiet)
echo "Created: $TARBALL"
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
Created: my-package-1.0.0.tgz
```

自定义目标目录：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm pack --destination ./dist
# 在 ./dist/ 目录保存 tar 包
```

## 选项

* `--dry-run`：执行所有任务，但不将压缩包写入磁盘。显示将包含的内容。
* `--destination <dir>`：保存压缩包的目录。
* `--filename <name>`：压缩包的确切文件名。
* `--ignore-scripts`：跳过运行 pre/postpack 和 prepare 脚本。
* `--gzip-level <0-9>`：设置 gzip 压缩级别，范围为 0 到 9（默认为 9）。
* `--quiet`：仅输出压缩包文件名，抑制其余输出。在脚本中很有用。

> **注意：** `--filename` 和 `--destination` 不能同时使用。

## 输出模式

**默认输出：**

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

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pack v1.2.19

packed 131B package.json
packed 40B index.js

my-package-1.0.0.tgz

Total files: 2
Shasum: f2451d6eb1e818f500a791d9aace80b394258a90
Unpacked size: 171B
Packed size: 249B
```

**静默输出：**

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

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
my-package-1.0.0.tgz
```

## bin

打印当前项目的 `bin` 目录路径：

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

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
/path/to/current/project/node_modules/.bin
```

打印全局 `bin` 目录路径：

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

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
<$HOME>/.bun/bin
```

## ls

要打印当前项目中已安装依赖及其解析后的版本，不包括它们的依赖：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm ls
# 或者
bun list
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
/path/to/project node_modules (135)
├── eslint@8.38.0
├── react@18.2.0
├── react-dom@18.2.0
├── typescript@5.0.4
└── zod@3.21.4
```

要打印所有已安装的依赖，包括第 n 阶依赖：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm ls --all
# 或者
bun list --all
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
/path/to/project node_modules (135)
├── @eslint-community/eslint-utils@4.4.0
├── @eslint-community/regexpp@4.5.0
├── @eslint/eslintrc@2.0.2
├── @eslint/js@8.38.0
├── @nodelib/fs.scandir@2.1.5
├── @nodelib/fs.stat@2.0.5
├── @nodelib/fs.walk@1.2.8
├── acorn@8.8.2
├── acorn-jsx@5.3.2
├── ajv@6.12.6
├── ansi-regex@5.0.1
├── ...
```

仅打印受信任的依赖（允许运行[生命周期脚本](/pm/lifecycle)的依赖）。当在 `package.json` 中设置了 `trustedDependencies` 时，Bun 会显示该列表中的软件包；否则会显示其[默认受信任依赖](https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt)列表中的软件包。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm ls --trusted
# 或者
bun list --trusted
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
/path/to/project node_modules (135)
└── esbuild@0.21.5
```

## licenses

列出每个已安装的软件包，并按照从 `node_modules` 中各软件包的 `package.json` 读取的许可证进行分组。没有 `license` 字段的软件包会列在 `Unknown` 下。只能通过 `devDependencies` 访问的软件包会标记为 `(dev)`。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm licenses
# or
bun pm licenses ls
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
MIT (2)
├── path-parse@1.0.6
└── resolve@1.9.0

Unknown (4)
├── a-dep@1.0.1 (dev)
├── no-deps@1.0.0
├── no-deps@1.0.1
└── one-dep@1.0.0
```

| Flag                           | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `--json`                       | 按许可证为键打印 JSON 对象                               |
| `--long`                       | 同时打印每个软件包的 `author`、`description` 和 `homepage` |
| `--prod`、`-p`                  | 跳过 `devDependencies`（等同于 `--omit=dev`）         |
| `--dev`、`-D`                   | 仅列出由 `devDependencies` 引入的内容                   |
| `--omit=<dev\|optional\|peer>` | 跳过一种依赖类型，与 `bun install` 中的行为相同                |
| `--filter <pattern>`、`-F`      | 仅列出匹配工作区的依赖（[筛选语法](/pm/filter)）                |

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm licenses --json --prod
```

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "MIT": [
    {
      "name": "path-parse",
      "versions": ["1.0.6"],
      "paths": ["/home/me/app/node_modules/path-parse"],
      "license": "MIT",
      "homepage": "https://github.com/jbgutierrez/path-parse#readme",
      "author": "Javier Blanco <http://jbgutierrez.info>",
      "description": "Node.js path.parse() ponyfill"
    }
  ]
}
```

在工作区根目录中，会列出每个工作区的依赖；在工作区软件包内部，则只列出该软件包的依赖。使用 [`bun why`](/pm/cli/why) 可查明是什么引入了意外的软件包。

需要同时存在 `bun.lock` 和 `node_modules`。锁文件中存在但 `node_modules` 中缺失的软件包（例如执行 `bun install --production` 后）会被跳过，并显示警告。

## whoami

打印你的 npm 用户名。需要已登录（`bunx npm login`）并在 `bunfig.toml` 或 `.npmrc` 中保存凭据：

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

## 哈希

生成并打印当前锁文件的哈希：

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

打印用于哈希锁文件的字符串：

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

打印当前锁文件中存储的哈希：

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

## 缓存

打印 Bun 的全局模块缓存路径：

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

清除 Bun 的全局模块缓存：

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

## 迁移

迁移其他包管理器的锁文件，不安装任何东西：

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

## 未受信任

打印当前带有脚本的未受信任依赖：

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

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
./node_modules/@biomejs/biome @1.8.3
 » [postinstall]: node scripts/postinstall.js

这些依赖在安装时其生命周期脚本被阻止运行。
```

## trust

运行未受信任依赖的脚本并添加到 `trustedDependencies`：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm trust <names>
```

`trust` 命令选项：

* `--all`：信任所有未受信任的依赖。

## default-trusted

打印默认可信赖依赖列表：

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

查看 [GitHub 上的当前列表](https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt)。

## version

显示当前包版本及帮助信息：

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

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm version v1.3.3 (ca7428e9)
当前包版本：v1.0.0

版本增量：
  patch      1.0.0 → 1.0.1
  minor      1.0.0 → 1.1.0
  major      1.0.0 → 2.0.0
  prerelease 1.0.0 → 1.0.1-0
  prepatch   1.0.0 → 1.0.1-0
  preminor   1.0.0 → 1.1.0-0
  premajor   1.0.0 → 2.0.0-0
  from-git   使用最新 git 标签的版本
  1.2.3      设置指定版本

选项：
  --no-git-tag-version 跳过 git 操作
  --allow-same-version 避免版本相同时报错
  --message=<val>、-m  自定义提交信息，使用 %s 代替版本号
  --preid=<val>        预发行标识（例如 beta → 1.0.1-beta.0）
  --force、-f          跳过检查 git 是否脏状态

示例：
  bun pm version patch
  bun pm version 1.2.3 --no-git-tag-version
  bun pm version prerelease --preid beta --message "Release beta: %s"
```

在 `package.json` 中升级版本：

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

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
v1.0.1
```

支持 `patch`、`minor`、`major`、`premajor`、`preminor`、`prepatch`、`prerelease`、`from-git`，或类似 `1.2.3` 的指定版本。默认情况下会创建 git 提交和标签；传入 `--no-git-tag-version` 可跳过这些操作。

## pkg

管理 `package.json` 数据，可进行获取、设置、删除及修复操作。

所有命令支持点号和中括号路径表示法：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
scripts.build              # 点号表示法
contributors[0]            # 访问数组项
workspaces.0               # 数字索引的点号表示法
scripts[test:watch]        # 中括号表示特殊字符
```

示例：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 获取
bun pm pkg get name                               # 单个属性
bun pm pkg get name version                       # 多个属性
bun pm pkg get                                    # 整个 package.json
bun pm pkg get scripts.build                      # 嵌套属性

# 设置
bun pm pkg set name="my-package"                  # 简单属性
bun pm pkg set scripts.test="jest" version=2.0.0  # 多个属性
bun pm pkg set private=true --json                # 使用 --json 标志的 JSON 值

# 删除
bun pm pkg delete description                     # 单个属性
bun pm pkg delete scripts.test contributors[0]    # 多个或嵌套属性

# 修复
bun pm pkg fix                                    # 自动修复常见问题
```