.npmrc 支持
Bun 会从 .npmrc 文件中加载配置选项,因此你可以复用现有的注册表和作用域配置。
配置按以下顺序加载,后面的来源会覆盖前面的来源:
~/.npmrc(或$XDG_CONFIG_HOME/.npmrc)./.npmrcbunfig.toml(全局,然后项目)BUN_CONFIG_REGISTRY/NPM_CONFIG_REGISTRY和BUN_CONFIG_TOKEN/NPM_CONFIG_TOKEN环境变量--registry等命令行标志
Bun 会将 .npmrc 中的凭据(//<registry>/:_authToken 等)按主机和路径匹配到注册表,即使你在 bunfig.toml 中设置了注册表 URL 也是如此。
值可以引用环境变量。Bun 会将 ${NAME} 替换为该变量的值;如果变量未设置,则保留原样。如果变量未设置,${NAME?} 会变为空字符串。
支持的选项
设置默认的 registry
Bun 从默认 registry 中解析软件包,该 registry 是 npm 的官方 registry(https://registry.npmjs.org/)。
要更改它,请在 .npmrc 中设置 registry 选项:
registry=http://localhost:4873/
对应的 bunfig.toml 选项是 install.registry:
install.registry = "http://localhost:4873/"
为特定作用域设置 registry
@<scope>:registry 为特定作用域设置 registry:
@myorg:registry=http://localhost:4873/
对应的 bunfig.toml 选项是在 install.scopes 中添加一个键:
[install.scopes]
myorg = "http://localhost:4873/"
配置特定 registry 的选项
//<registry_url>/:<key>=<value> 为特定 registry 设置选项:
# 为 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 支持以下选项:
_authTokenusername_password(经过 base64 编码的密码)_auth(经过 base64 编码的 username:password,例如btoa(username + ":" + password))email
对应的 bunfig.toml 选项是在 install.scopes 中添加一个键:
[install.scopes]
# 与 .npmrc 中的 _password 不同,password 未经过 base64 编码;Bun 会为你编码
myorg = { url = "http://localhost:4873/", username = "myusername", password = "$NPM_PASSWORD" }
link-workspace-packages:控制工作区包的安装
控制 Bun 在工作区包可在本地获取时如何安装它们:
link-workspace-packages=true
对应的 bunfig.toml 选项是 install.linkWorkspacePackages:
[install]
linkWorkspacePackages = true
save-exact:保存确切版本
始终保存确切版本,不带 ^ 前缀:
save-exact=true
对应的 bunfig.toml 选项是 install.exact:
[install]
exact = true
ignore-scripts:跳过生命周期脚本
防止在安装时运行生命周期脚本:
ignore-scripts=true
这相当于使用 bun install 的 --ignore-scripts 标志。
dry-run:预览变更但不安装
显示 Bun 在不实际安装任何内容的情况下会安装什么:
dry-run=true
对应的 bunfig.toml 选项是 install.dryRun:
[install]
dryRun = true
cache:配置缓存目录
设置缓存目录路径,或禁用缓存:
# 设置自定义缓存目录
cache=/path/to/cache
# 或禁用缓存
cache=false
对应的 bunfig.toml 选项是 install.cache:
[install.cache]
# 设置自定义缓存目录
dir = "/path/to/cache"
# 或禁用缓存
disable = true
ca 和 cafile:配置 CA 证书
为 registry 连接配置自定义 CA 证书:
# 单个 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 安装哪些类型的依赖:
# 忽略开发依赖
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:
# 扁平 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 |
# 符号链接 / 隔离模式
node-linker=isolated
node-linker=pnpm
# 扁平 / 托举模式
node-linker=hoisted
node-linker=node-modules
public-hoist-pattern 和 hoist-pattern:控制托举
控制 Bun 将哪些软件包托举到根目录的 node_modules:
# 匹配该模式的包将被托举到根目录
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