.npmrc 支持

Bun 会从 .npmrc 文件中加载配置选项，因此你可以复用现有的注册表和作用域配置。配置按以下顺序加载，后面的来源会覆盖前面的来源：

~/.npmrc（或 $XDG_CONFIG_HOME/.npmrc）
./.npmrc
bunfig.toml（全局，然后项目）
BUN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY 和 BUN_CONFIG_TOKEN / NPM_CONFIG_TOKEN 环境变量
--registry 等命令行标志

Bun 会将 .npmrc 中的凭据（//<registry>/:_authToken 等）按主机和路径匹配到注册表，即使你在 bunfig.toml 中设置了注册表 URL 也是如此。值可以引用环境变量。Bun 会将 ${NAME} 替换为该变量的值；如果变量未设置，则保留原样。如果变量未设置，${NAME?} 会变为空字符串。

我们建议将你的 .npmrc 文件迁移到 Bun 的 bunfig.toml 格式，该格式支持更多选项，包括 Bun 专属选项。

支持的选项

设置默认的 registry

Bun 从默认 registry 中解析软件包，该 registry 是 npm 的官方 registry（https://registry.npmjs.org/）。要更改它，请在 .npmrc 中设置 registry 选项：

.npmrc

registry=http://localhost:4873/

对应的 bunfig.toml 选项是 install.registry：

bunfig.toml

install.registry = "http://localhost:4873/"

为特定作用域设置 registry

@<scope>:registry 为特定作用域设置 registry：

.npmrc

@myorg:registry=http://localhost:4873/

对应的 bunfig.toml 选项是在 install.scopes 中添加一个键：

bunfig.toml

[install.scopes]
myorg = "http://localhost:4873/"

配置特定 registry 的选项

//<registry_url>/:<key>=<value> 为特定 registry 设置选项：

.npmrc

# 为 registry 设置认证令牌
# ${...} 是环境变量的占位符
//http://localhost:4873/:_authToken=${NPM_TOKEN}


# 或者你可以设置用户名和密码
# 注意密码是 base64 编码过的
//http://localhost:4873/:username=myusername

//http://localhost:4873/:_password=${NPM_PASSWORD}

# 或者使用 _auth，它是用户名和密码合并成一个字符串后 base64 编码的结果
//http://localhost:4873/:_auth=${NPM_AUTH}

Bun 支持以下选项：

_authToken
username
_password（经过 base64 编码的密码）
_auth（经过 base64 编码的 username:password，例如 btoa(username + ":" + password)）
email

对应的 bunfig.toml 选项是在 install.scopes 中添加一个键：

bunfig.toml

[install.scopes]
# 与 .npmrc 中的 _password 不同，password 未经过 base64 编码；Bun 会为你编码
myorg = { url = "http://localhost:4873/", username = "myusername", password = "$NPM_PASSWORD" }

`link-workspace-packages`：控制工作区包的安装

控制 Bun 在工作区包可在本地获取时如何安装它们：

.npmrc

link-workspace-packages=true

对应的 bunfig.toml 选项是 install.linkWorkspacePackages：

bunfig.toml

[install]
linkWorkspacePackages = true

`save-exact`：保存确切版本

始终保存确切版本，不带 ^ 前缀：

.npmrc

save-exact=true

对应的 bunfig.toml 选项是 install.exact：

bunfig.toml

[install]
exact = true

`ignore-scripts`：跳过生命周期脚本

防止在安装时运行生命周期脚本：

.npmrc

ignore-scripts=true

这相当于使用 bun install 的 --ignore-scripts 标志。

`dry-run`：预览变更但不安装

显示 Bun 在不实际安装任何内容的情况下会安装什么：

.npmrc

dry-run=true

对应的 bunfig.toml 选项是 install.dryRun：

bunfig.toml

[install]
dryRun = true

`cache`：配置缓存目录

设置缓存目录路径，或禁用缓存：

.npmrc

# 设置自定义缓存目录
cache=/path/to/cache

# 或禁用缓存
cache=false

对应的 bunfig.toml 选项是 install.cache：

bunfig.toml

[install.cache]
# 设置自定义缓存目录
dir = "/path/to/cache"

# 或禁用缓存
disable = true

`ca` 和 `cafile`：配置 CA 证书

为 registry 连接配置自定义 CA 证书：

.npmrc

# 单个 CA 证书
ca="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# 多个 CA 证书
ca[]="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
ca[]="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"

# 或指定 CA 文件路径
cafile=/path/to/ca-bundle.crt

`omit` 和 `include`：控制依赖类型

控制 Bun 安装哪些类型的依赖：

.npmrc

# 忽略开发依赖
omit=dev

# 忽略多种类型
omit[]=dev
omit[]=optional

# 包含指定类型（覆盖 omit）
include=dev

有效值：dev，peer，optional

`install-strategy` 和 `node-linker`：安装策略

控制 Bun 在 node_modules 中如何组织软件包。为兼容其他包管理器，Bun 同时接受 npm 的 install-strategy 和 pnpm/yarn 的 node-linker。有关托举式和隔离式布局的区别，请参阅隔离安装。 npm 的 install-strategy：

.npmrc

# 扁平 node_modules 结构（默认）
install-strategy=hoisted

# 符号链接结构
install-strategy=linked

pnpm / yarn 的 node-linker： node-linker 控制安装模式。Bun 接受来自 pnpm 和 yarn 的值：

值	描述	接受者
`isolated`	符号链接结构，带有隔离依赖	pnpm
`hoisted`	扁平 node_modules 结构	pnpm
`pnpm`	符号链接结构（等同于 `isolated`）	yarn
`node-modules`	扁平 node_modules 结构（等同于 `hoisted`）	yarn

.npmrc

# 符号链接 / 隔离模式
node-linker=isolated
node-linker=pnpm

# 扁平 / 托举模式
node-linker=hoisted
node-linker=node-modules

`public-hoist-pattern` 和 `hoist-pattern`：控制托举

控制 Bun 将哪些软件包托举到根目录的 node_modules：

.npmrc

# 匹配该模式的包将被托举到根目录
public-hoist-pattern=*eslint*

# 多个模式
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

# 控制通用的托举行为
hoist-pattern=*

# 仅适用于 isolated linker：禁用 node_modules/.bun/node_modules 回退机制，
# 使存储包只解析已声明的依赖项（以及根目录的 node_modules）。
# 托举式安装会忽略此设置。
hoist=false

核心命令

发布与分析

工作区管理

高级配置

支持的选项

设置默认的 registry

为特定作用域设置 registry

配置特定 registry 的选项

`link-workspace-packages`：控制工作区包的安装

`save-exact`：保存确切版本

`ignore-scripts`：跳过生命周期脚本

`dry-run`：预览变更但不安装

`cache`：配置缓存目录

`ca` 和 `cafile`：配置 CA 证书

`omit` 和 `include`：控制依赖类型

`install-strategy` 和 `node-linker`：安装策略

`public-hoist-pattern` 和 `hoist-pattern`：控制托举

​支持的选项

​设置默认的 registry

​为特定作用域设置 registry

​配置特定 registry 的选项

​link-workspace-packages：控制工作区包的安装

​save-exact：保存确切版本

​ignore-scripts：跳过生命周期脚本

​dry-run：预览变更但不安装

​cache：配置缓存目录

​ca 和 cafile：配置 CA 证书

​omit 和 include：控制依赖类型

​install-strategy 和 node-linker：安装策略

​public-hoist-pattern 和 hoist-pattern：控制托举

支持的选项

设置默认的 registry

为特定作用域设置 registry

配置特定 registry 的选项

`link-workspace-packages`：控制工作区包的安装

`save-exact`：保存确切版本

`ignore-scripts`：跳过生命周期脚本

`dry-run`：预览变更但不安装

`cache`：配置缓存目录

`ca` 和 `cafile`：配置 CA 证书

`omit` 和 `include`：控制依赖类型

`install-strategy` 和 `node-linker`：安装策略

`public-hoist-pattern` 和 `hoist-pattern`：控制托举