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

> 使用 `bun publish` 将包发布到 npm 注册表

`bun publish` 会自动将你的包打包成 tarball，去除 `package.json` 中的 catalog 和 workspace 协议（如有必要会解析版本），并发布到配置文件中指定的注册表。支持 `bunfig.toml` 和 `.npmrc` 文件。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
## 从当前工作目录发布包
bun publish
```

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
bun publish v1.3.3 (ca7428e9)

packed 203B package.json
packed 224B README.md
packed 30B index.ts
packed 0.64KB tsconfig.json

Total files: 4
Shasum: 79e2b4377b63f4de38dc7ea6e5e9dbee08311a69
Integrity: sha512-6QSNlDdSwyG/+[...]X6wXHriDWr6fA==
Unpacked size: 1.1KB
Packed size: 0.76KB
Tag: latest
Access: default
Registry: http://localhost:4873/

 + publish-1@1.0.0
```

或者，你也可以先用 `bun pm pack` 单独打包你的包，然后用 `bun publish` 指定输出的 tarball 路径进行发布。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun pm pack
...
bun publish ./package.tgz
```

<Note>
  当提供 tarball 路径时，`bun publish` 不会执行生命周期脚本（`prepublishOnly/prepack/prepare/postpack/publish/postpublish`）。只有在由 `bun publish` 打包时才会执行脚本。
</Note>

### `--access`

`--access` 标志可用于设置发布包的访问级别。访问级别可以是 `public` 或 `restricted`。未作用域的包总是公开的，尝试使用 `--access restricted` 发布未作用域包将导致错误。

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

也可以在 `package.json` 的 `publishConfig` 字段中设置 `--access`。

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "publishConfig": {
    "access": "restricted"
  }
}
```

### `--tag`

设置发布的包版本的标签。默认标签为 `latest`。包的初始版本总是会被打上 `latest` 标签，且会额外打上指定的标签。

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

也可以在 `package.json` 的 `publishConfig` 字段中设置 `--tag`。

```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "publishConfig": {
    "tag": "next"
  }
}
```

### `--dry-run`

`--dry-run` 标志可用于模拟发布过程，而不实际发布包。这对于验证发布包的内容很有用。

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

### `--tolerate-republish`

如果包版本已存在，使用该标志时退出码为 0 而不是 1。在可能重新运行作业的 CI/CD 场景中很有用。

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

### `--gzip-level`

指定打包时使用的 gzip 压缩等级。仅适用于无 tarball 路径参数的 `bun publish`。取值范围为 `0` 到 `9`（默认值为 `9`）。

### `--auth-type`

如果你的 npm 账号启用了两步验证（2FA），`bun publish` 会提示输入一次性密码。该操作既可以通过浏览器，也可以通过 CLI 完成。`--auth-type` 标志用于告诉 npm 注册表你偏好的验证方式。可选值为 `web` 和 `legacy`，默认值是 `web`。

```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun publish --auth-type legacy
...
This operation requires a one-time password.
Enter OTP: 123456
...
```

### `--otp`

直接向 CLI 提供一次性密码。如果密码有效，将跳过发布前的额外一次性密码提示。示例如下：

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

<Note>
  `bun publish` 支持 `NPM_CONFIG_TOKEN` 环境变量，可用于 github actions 或自动化工作流中的发布。
</Note>

***

## CLI 使用方法

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

### 发布选项

<ParamField path="--access" type="string">
  `--access` 标志用于设置将要发布包的访问级别。访问级别可以是 `public` 或 `restricted`。非作用域包始终是公开的，尝试使用 `--access restricted` 发布非作用域包会导致错误。

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

  也可以在 `package.json` 的 `publishConfig` 字段中设置 `--access`。

  ```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
  {
    "publishConfig": {
      "access": "restricted" // [!code ++]
    }
  }
  ```
</ParamField>

<ParamField path="--tag" type="string" default="latest">
  设置发布的包版本标签。默认标签是 `latest`。包的初始版本始终会获得 `latest` 标签，此外还会标记指定的标签。

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

  也可以在 `package.json` 的 `publishConfig` 字段中设置 `--tag`。

  ```json package.json icon="file-json" theme={"theme":{"light":"github-light","dark":"dracula"}}
  {
    "publishConfig": {
      "tag": "next" // [!code ++]
    }
  }
  ```
</ParamField>

<ParamField path="--dry-run=<val>" type="string">
  `--dry-run` 标志用于模拟发布过程，但不实际发布包。此功能适用于在不发布包的情况下验证发布包的内容。

  ```sh theme={"theme":{"light":"github-light","dark":"dracula"}}
  bun publish --dry-run
  ```
</ParamField>

<ParamField path="--gzip-level" type="string" default="9">
  指定打包时使用的 gzip 压缩级别。仅适用于没有使用 tarball 路径参数的 `bun publish`。数值范围是 `0` 到 `9`（默认是 `9`）。
</ParamField>

<ParamField path="--auth-type" type="string" default="web">
  如果你的 npm 账户启用了两步验证（2FA），`bun publish` 会提示输入一次性密码（OTP）。这可以通过浏览器或命令行完成。`--auth-type` 标志用于告知 npm 注册表你更倾向使用哪种方式。可选值为 `web` 和 `legacy`，默认是 `web`。

  ```sh terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
  bun publish --auth-type legacy
  ...
  This operation requires a one-time password.
  Enter OTP: 123456
  ...
  ```
</ParamField>

<ParamField path="--otp" type="string" default="web">
  直接向命令行提供一次性密码。如果密码有效，在发布之前会跳过额外的一次性密码提示。例如：

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

  <Note>
    `bun publish` 会尊重环境变量 `NPM_CONFIG_TOKEN`，可以在 Github Actions 或自动化工作流中使用。
  </Note>
</ParamField>

### 注册表配置

#### 自定义注册表

<ParamField path="--registry" type="string">
  指定注册表 URL，覆盖 .npmrc 和 bunfig.toml 配置
</ParamField>

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bun publish --registry https://my-private-registry.com
```

#### SSL 证书

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

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

<CodeGroup>
  ```bash Inline Certificate theme={"theme":{"light":"github-light","dark":"dracula"}}
  bun publish --ca "-----BEGIN CERTIFICATE-----..."
  ```

  ```bash Certificate File theme={"theme":{"light":"github-light","dark":"dracula"}}
  bun publish --cafile ./ca-cert.pem
  ```
</CodeGroup>

### 发布选项

#### 依赖管理

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

<ParamField path="--omit" type="string">
  排除依赖类型：`dev`、`optional` 或 `peer`
</ParamField>

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

#### 脚本控制

<ParamField path="--ignore-scripts" type="boolean">
  打包和发布时跳过生命周期脚本
</ParamField>

<ParamField path="--trust" type="boolean">
  将包添加到 trustedDependencies 并运行其脚本
</ParamField>

<Note>
  **生命周期脚本** — 当提供预构建的 tarball 时，生命周期脚本（如 prepublishOnly、prepack 等）不会执行。只有当 Bun 自己打包包时，才会运行脚本。
</Note>

#### 文件管理

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

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

<ParamField path="--yarn" type="boolean">
  生成 yarn.lock 文件（兼容 yarn v1）
</ParamField>

#### 性能

<ParamField path="--backend" type="string">
  平台优化选项：`clonefile`（默认）、`hardlink`、`symlink` 或 `copyfile`
</ParamField>

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

<ParamField path="--concurrent-scripts" type="number" default="5">
  最大并发生命周期脚本数
</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>