第七章相关配置

7 分钟阅读

第七章　相关配置

📌 版本提示（2026-09 核对）：以下配置以 Bun 1.4.x 为基准；旧版 Bun 的字段和默认值可能不同，升级前请对照官方 bunfig.toml 文档。

🤓 本章聊聊 Bun 的各种"花式配置"——从配置文件到环境变量，从国内镜像加速到 IDE 配合，手把手把你打造成配置大师。

7.1 bunfig.toml（全局配置文件）

如果说 Bun 是一个狂飙的老司机，那 bunfig.toml 就是它的外挂副驾驶——全局配置，想怎么调就怎么调。

它长得有点像 .npmrc 和 tsconfig.json 的远房亲戚，但脾气比它们都好使。

文件位置

全局：~/.bunfig.toml（推荐，大多数人装一次就够了）
项目级：./bunfig.toml（项目专属，千人千面）
指定路径：通过命令行 -c myconfig.toml 指定，或者配合环境变量（见后文）

常用配置项

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# bunfig.toml

[install]
# npm 镜像源（解决国内下载慢的问题）
registry = "https://registry.npmmirror.com"

# 生产模式（跳过 devDependencies）
production = false

# 自动安装策略
# auto      → 找不到就自动安装（默认）
# fallback  → 优先用缓存，缓存没有再装
# force     → 强制重新安装，不管缓存
# none      → 离线模式，装不了就摆烂
auto = "fallback"

# 跳过 scripts（安装前后自动执行的脚本）
ignore-scripts = false

# 安装可选依赖（optionalDependencies）
optional = true

[install.cache]
# 缓存目录
dir = "~/.bun/cache"

国内镜像配置

1
2
3
# bunfig.toml（解决 npm 安装慢的问题）
[install]
registry = "https://registry.npmmirror.com"

配置后，所有 bun install 命令都会使用镜像源，速度飙升！🚀

离线模式

1
2
3
[install]
# 强制离线模式，找不到包也绝不联网
auto = "none"

bunfig vs 环境变量优先级

环境变量优先级更高。如果同时配置了 bunfig.toml 和 BUN_CONFIG_REGISTRY，环境变量会覆盖配置文件。

1
2
# 环境变量覆盖 bunfig.toml
BUN_CONFIG_REGISTRY=https://registry.npmmirror.com bun install

日志级别

1
2
# 控制 bun 的输出详细程度
logLevel = "warning"  # debug | info | warning | error

7.2 bun.lock（锁文件）

📌 重要变更（Bun v1.2 起）：Bun 的默认锁文件已经改成文本格式的 bun.lock（JSONC 风格，可读、可 diff、冲突好处理）。老的二进制文件 bun.lockb 是 1.2 之前的产物：Bun 仍然能读它，但默认不再生成它。很多老教程还在讲 bun.lockb，那已经是历史了。

为什么要用锁文件？

想象一下：团队五个人，同样的 package.json，结果装了五个不同版本的 lodash——那画面太美我不敢看。锁文件就是为了终结这种"玄学 bug"而生的。

锁文件格式说明

bun.lock 是文本格式，一般也不需要手动编辑。改坏了怎么办？删掉重装就行：

1
2
3
4
5
6
7
8
rm bun.lock
bun install          # 重新生成 bun.lock

# 只想生成/更新锁文件、不装到 node_modules：
bun install --lockfile-only

# 从旧的二进制锁文件迁移到文本锁文件（迁移后手动删除 bun.lockb）
bun install --save-text-lockfile --frozen-lockfile --lockfile-only

另外两个常用的开关：

bun install --no-save：装依赖但不写锁文件（临时试装用，别在团队项目里当常规操作）；
bun install --frozen-lockfile（或直接 bun ci）：CI 里要求"锁文件必须和 package.json 完全一致"，否则报错退出——这才是可复现构建该用的命令。

自动迁移：如果项目里只有 yarn.lock、package-lock.json（lockfileVersion 2/3/4）或 pnpm-lock.yaml，第一次运行 bun install 时 Bun 会自动读取并转换它们（原锁文件会保留，验证无误后可自行删除）。注意 npm 6 及更早的 lockfileVersion: 1 不会被迁移，Bun 会打印警告并直接从 package.json 解析。

与其他锁文件的区别

锁文件	格式	可读性
bun.lock	文本（JSONC 风格）	✅ 可读、可 diff（Bun 1.2+ 默认）
bun.lockb	二进制	⚠️ 旧格式，仍被读取但没有必要再用
package-lock.json	JSON	✅ 可读
yarn.lock	类 YAML 的自定义格式	✅ 可读
pnpm-lock.yaml	YAML	✅ 可读

提交到 Git

锁文件一定要提交到 Git！否则团队其他成员拉了代码，bun install 装出来的包版本可能和你不一致，“在我电脑上是好的"这种经典剧情又要上演了。

7.3 package.json 中的 Bun 配置

overrides（依赖覆盖）

强制统一依赖树中某个包的版本，解决传递依赖冲突的利器：

1
2
3
4
5
6
7
8
{
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "overrides": {
    "lodash": "^4.17.21"  // 所有依赖树里的 lodash 都用这个版本
  }
}

💡 overrides 在 Bun、pnpm 和 npm 7+ 中都支持。

bun 特定字段

1
2
3
4
5
6
7
{
  "scripts": {
    "install": "bun install",       // 安装时自动运行
    "prepack": "bun run build",     // npm pack 前自动运行
    "postpack": "bun run clean"     // npm pack 后自动运行
  }
}

workspace / monorepo 配置

1
2
3
4
5
6
{
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

1
2
# 工作区根目录运行，一键安装所有 workspace 包
bun install

7.4 环境变量配置

常用环境变量

变量	说明	示例
`BUN_INSTALL`	Bun 安装路径	`~/.bun`
`BUN_ENV`	环境标识	`development` / `production`
`BUN_CONFIG_REGISTRY`	镜像源	`https://registry.npmmirror.com`
`BUN_CACHE_DIR`	缓存目录	`~/.bun/cache`
`HTTP_PROXY`	HTTP 代理	`http://localhost:7890`
`HTTPS_PROXY`	HTTPS 代理	`http://localhost:7890`

BUN_ENV

这个变量决定了 Bun 运行时的心境——是"认真打工"还是"摸鱼划水”：

1
2
3
4
5
6
// 根据环境加载不同配置
if (process.env.BUN_ENV === "production") {
  console.log("生产环境模式！");
} else {
  console.log("开发环境模式！");
}

1
BUN_ENV=production bun run server.ts

7.5 国内镜像加速 🇨🇳

好消息：配置很简单。坏消息：你得先知道配哪里。

npmmirror（原淘宝镜像）

一行配置，告别龟速下载：

1
2
3
# ~/.bunfig.toml
[install]
registry = "https://registry.npmmirror.com"

或者直接写进 shell 配置：

1
2
echo 'export BUN_CONFIG_REGISTRY=https://registry.npmmirror.com' >> ~/.bashrc
source ~/.bashrc

临时指定镜像

不想改全局配置？一次性的，用命令行参数：

1
bun install --registry https://registry.npmmirror.com

不同包管理器共用镜像的坑

npm、pnpm、Bun 三兄弟的镜像配置是各自独立的：

npm → ~/.npmrc
pnpm → ~/.config/pnpm/npmrc（默认）
Bun → ~/.bunfig.toml

光给一个工具配了镜像其他工具还是原装的龟速，等于没配。

7.6 IDE 与编辑器支持

好马配好鞍，好代码配好 IDE。

VS Code

VS Code 对 Bun 的支持非常贴心：

Bun Language Features：语法高亮、智能补全、类型提示全安排
Bun Debugger：断点调试，想停哪停哪

去 VS Code 扩展市场搜 “Bun”，安装官方插件就行。

WebStorm

WebStorm 原生支持 Bun，2024.1+ 版本无需安装任何插件，开箱即用。

Neovim

1
2
3
4
-- init.vim 或 init.lua
local lspconfig = require("lspconfig")

lspconfig.bun.setup({})

配合 nvim-lspconfig 使用，Bun 的 LSP 服务自动启动。

7.7 与 Node.js 共存配置

好消息：Bun 和 Node.js 可以和平共处，不需要二选一。

PATH 优先级

谁先被找到，取决于 PATH 里的顺序：

1
2
3
4
5
6
7
# 查看当前 bun 的路径
which bun
# /home/user/.bun/bin/bun

# 查看 node 的路径
which node
# /usr/local/bin/node

想让 bun 优先于系统的 node？把 bun 的路径放 PATH 前面：

1
2
3
# ~/.bashrc 或 ~/.zshrc
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

⚠️ 顺手的事，但要注意——如果你有其他工具（如 fnm、nvm）也在管 node，别让它们的 PATH 配置互相打架。

CI/CD 中切换

1
2
3
4
5
6
7
8
9
# GitHub Actions 示例
- name: Install Bun
  uses: oven-sh/setup-bun@v1

- name: Install dependencies
  run: bun install

- name: Run tests
  run: bun test

官方 Action：oven-sh/setup-bun

7.8 诊断工具

Bun 自带了一套"体检套餐"，帮你快速定位环境问题。

环境自检怎么做

⚠️ 先纠正一个常见误传：截至 Bun 1.4.2，官方文档里没有 bun doctor 这条命令。你在别处看到 bun doctor 的输出示例（“Checking for Bun…“那一类），不要照抄——运行时会直接报未知命令。

排查环境问题，官方的可靠做法是这几条：

1
2
3
4
5
bun --version      # 我装的是哪个版本
bun --revision     # 版本的完整信息（含 commit）
bun upgrade        # 升级到最新版
bun pm cache       # 缓存相关：查看缓存目录
bun install --verbose   # 安装出错时打开详细日志，看真正卡在哪一步

再配合 which bun / which node（Windows 上是 where bun）确认 PATH 里谁在前面，绝大多数"环境不对劲"的问题都能定位。

bun –version - 查看版本

1
2
bun --version
# 1.3.11

bun pm - 包管理器工具集

1
2
3
bun pm ls     # 列出已安装的包
bun pm bin    # 列出 bun 安装目录
bun pm cache dir  # 显示缓存目录路径

bun info - 查看包信息

1
2
3
4
bun info react
# react@18.2.0
# Latest: 18.3.1
# Description: React is a JavaScript library for building user interfaces.

本章小结

本章介绍了 Bun 的配置体系，帮你从"会用"进化到"会配”。

bunfig.toml 是 Bun 的全局配置文件，可配置镜像源、缓存目录、自动安装行为、日志级别等。国内用户最重要的配置就是镜像——配完就能明显感到差别。锁文件：1.2 起默认是文本格式的 bun.lock（取代二进制的 bun.lockb），必须提交到 Git；CI 里用 bun install --frozen-lockfile 或 bun ci 保证可复现安装。package.json 中的 Bun 配置：overrides 用于强制依赖版本，scripts 中可以指定 bun 命令，workspaces 配置 monorepo。环境变量：BUN_INSTALL、BUN_ENV、BUN_CONFIG_REGISTRY、BUN_CACHE_DIR 等都是高频使用的配置项。国内镜像：bunfig.toml 中配一行 registry 就够了。IDE 支持：VS Code 装插件、WebStorm 原生支持、Neovim 配 LSP，各取所需。与 Node.js 共存：两者可以同时装，通过 PATH 决定谁出场。诊断工具：bun --version、bun --revision、bun pm cache、bun install --verbose（注意：截至 1.4.2 官方没有 bun doctor 命令）。

配置好的 Bun，配上国内镜像——这时候你再回头看 npm 的速度，就像在老式电脑上跑 VS Code。差距，就是这么残酷。

最后修改 September 19, 2026: 更新 (3489033b1)

第七章 相关配置