使用 Bun 替代 Node 运行 Vite 项目

发表于 分类于
说明如何用 Bun 安装依赖、配置 registry 镜像、执行脚本并跑通 Vite 开发与构建，以及迁移时常见注意点。

前言

Vite 本身是面向现代浏览器的构建工具，日常开发主要依赖 package.json 里的脚本与 npm 生态里的包。
Bun 实现了兼容 npm 的包管理与脚本运行能力，因此在许多项目里可以用它替代 Node 来装依赖和启动 vite。
本文面向已有 Vite 项目或准备新建项目的读者，说明从安装到 dev / build 的常用命令与边界。
不讨论生产环境用 Bun 跑 HTTP 服务或 SSR 适配器的细节，那部分需按框架文档单独评估。

环境准备

Bun 的安装方式随系统而异，下面给出常见入口，具体版本以官方为准。

在 macOS、Linux 或 WSL 上，可用官方安装脚本拉取当前平台的二进制并配置 PATH。

1
curl -fsSL https://bun.sh/install | bash

安装完成后执行版本命令，确认终端能找到 bun。

1
bun --version

在 Windows 上，官方文档推荐用 PowerShell 执行一键安装脚本，装好后新开终端再试 bun。

1
powershell -c "irm bun.sh/install.ps1 | iex"

该方式会拉取安装脚本并从上游（常见为 GitHub 等）下载二进制，跨境或公司网络限速时容易很慢甚至超时。
若你遇到这种情况，可任选下面一种替代路径。

winget：走微软软件源，在国内往往比直连 bun.sh 更稳定；包标识以 winget search bun 为准。

1
winget install -e --id Oven-sh.Bun

或者

直接使用NPM安装(最快)

1
npm install -g bun --registry=https://registry.npmmirror.com

实践

新建项目

若从零开始，可用官方脚手架创建模板，再用 Bun 安装依赖。

下面命令在非交互场景下创建 Vue 示例目录并进入，你可把模板名换成 react、vanilla 等。

1
2
3
bun create vite my-app --template vue
cd my-app
bun install

已有项目迁移

进入已有 Vite 项目根目录后，用 Bun 解析 package.json 并写入自己的锁文件。

首次迁移建议删掉旧的 node_modules（若存在），避免混用两套安装结果。

1
2
3
cd /path/to/your-vite-project
rm -rf node_modules
bun install

Bun 会生成 bun.lock（或你当前版本对应的锁文件），团队内需约定是否提交该锁文件与是否仍保留 package-lock.json。

依赖镜像

bun install 拉取的是 npm 生态里的包，默认走官方 registry。
国内网络下可改为 npmmirror 等公共镜像，以加速解析与下载；这与「安装 Bun 本体」不是一回事，只影响依赖源地址。

可以全局配置：在用户主目录创建 .bunfig.toml，常见路径为 $HOME/.bunfig.toml。
若环境变量 XDG_CONFIG_HOME 已设置，也可使用 $XDG_CONFIG_HOME/.bunfig.toml。
Windows 上等价于用户目录下的 .bunfig.toml，例如 C:/Users/你的用户名/.bunfig.toml。
这样本机所有未另行指定的项目都会默认使用该 registry。

在 Windows 上若要用资源管理器打开该目录（用户主目录，即全局 .bunfig.toml 所在文件夹），可在 PowerShell 中执行下面命令。

1
explorer $env:USERPROFILE

若你当前窗口是 cmd，写法如下。

1
explorer %USERPROFILE%

项目根目录则使用 bunfig.toml（与 package.json 同级，文件名无前置点）。
适合写入仓库，与团队对齐。
官方行为是：同时存在全局与项目配置时做浅合并，项目里的 bunfig.toml 覆盖全局同名字段。
命令行上的 --registry 仍可再覆盖文件里的设置。

下面 [install] 段落在「全局 .bunfig.toml」或「项目 bunfig.toml」中写法相同，按需只配一处或两处都配。

1
2
[install]
registry = "https://registry.npmmirror.com"

若只想临时试用镜像，可在单次安装命令上带 --registry 参数，不写配置文件。

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

镜像由第三方同步，与官方源在同步延迟或个别包行为上可能略有差异。
关键业务或安全敏感项目建议以官方源为准，或在 CI 中固定 registry 并做完整性校验。

开发服务器

package.json 里若有 dev 脚本（通常是 vite），用 Bun 调用即可，等价于以前用 npm run dev。

1
bun run dev

若脚本未定义，可直接用 bunx 拉起本地或临时的 vite 可执行文件。

1
bunx vite

终端应打印本地 URL，浏览器能打开即说明开发链路正常。

构建与预览

生产构建与预览同样走 package.json 中的脚本名即可。

1
2
bun run build
bun run preview

若脚本名为 vite build，Bun 会按字段调用，行为与在 Node 下执行一致的前提是依赖未使用仅支持 Node 的加载方式。

与脚本字段的关系

Bun 会读取 package.json 的 scripts 与 dependencies，多数 Vite 插件只要遵循标准 ESM/CommonJS 约定即可工作。
若某脚本在文档里写死 node ./tools/xxx.mjs，可改为 bun ./tools/xxx.mjs 或保留 Node 单独跑该一步。
engines 字段若写死 node 版本，CI 里改用 Bun 时可能被工具提示，可按需放宽或仅在文档中说明实际运行时。

注意

部分依赖包含 原生扩展 或 postinstall 里硬编码 node，这类包在 Bun 下可能失败，需要查发行说明或暂时用 Node 执行对应脚本。
团队 CI 若从 npm ci 改为 bun install --frozen-lockfile（或你版本支持的等价参数），要同步上传锁文件并调整缓存键。
遇到与 Vite 无关的 仅 Node API 脚本（例如某些定制 server.js），仍可用系统里的 Node 跑，Bun 与 Node 可以并存，不必一刀切。

验证

在项目根执行开发命令后，确认终端无报错且 HMR 正常。

再执行构建，检查 dist 目录是否生成且 preview 能打开页面。

1
2
3
bun run dev
# 另开终端
bun run build && bun run preview

若任一步报错，把完整错误信息对照依赖仓库 issue，通常能区分是 Bun 兼容性还是项目配置问题。