Skip to main content
Bun 可以充当 Extension.js 项目的包管理器和脚本运行器。Extension.js 会检测到 Bun,把它记录进 package.json,并在自己的输出里打印 Bun 命令。 从 Extension.js 4.1.21 开始,CLI 也能跑在 Bun 上,需要 Bun 1.2 或更新版本。下面那个问题分成两半,而它们的答案已经和以前不一样了。

我可以用 Bun 代替 Node 吗?

对你的项目来说可以,对 CLI 进程来说也可以。 普通的 bunx extension 仍然会把 CLI 跑在 Node 上,因为发布出去的可执行文件带着 #!/usr/bin/env node 这行 shebang。加上 --bun,或者在 bunfig.toml 里设置 run.bun,才会在 Bun 上执行。

用 Bun 创建项目

Extension.js 看得出是 Bun 调用了它。它打印出来的后续步骤会点名 Bun:
生成的 package.json 会固定住你用的那个管理器:
package.json

安装与构建

这会写下一个 bun.lock 文件。之后每次运行,Extension.js 都会读取这个锁文件,以便继续选择 Bun。
脚手架写下的脚本与管理器无关。每一条都调用 extension 这个可执行文件,所以 bun run dev、bun run build 和 bun run preview 都能用。

哪些 Bun 版本可用

Extension.js 需要 Bun 1.2 或更新版本。CLI 在启动时读取 process.versions.bun,按 Bun 自己的版本来判断,而不是按 Bun 报告的 Node 版本,因为这两者并不同步:Bun 1.1.38 和 Bun 1.2.0 都报告 Node 22.6.0,但只有其中一个能跑完构建。 低于 1.2 的 Bun 无法加载 rspack 的原生绑定,所以旧版本不是在门口被拦下,而是在打包器深处失败。守卫会先把它拦住:
Bun 是通过 process.versions.bun 识别的,这个值由运行时自己设置,所以进入 Bun 的每一条路径都被覆盖:bunx 和 bun run 上的 --bun 标志,以及 bunfig.toml 里的 run.bun 默认值。

Extension.js 如何检测 Bun

检测读的是项目,而不是你敲下的那条命令。有三个信号喂给它:
  • 项目根目录下的 bun.lock 或 bun.lockb 锁文件。
  • package.json 里点名 bun 的 packageManager 字段。
  • Bun 运行脚本时设置的 npm_config_user_agent 环境变量。
Extension.js 支持 npm、pnpm、yarn、bun 和 deno。当一个信号都没有时,它会按 pnpm、yarn、bun 的顺序去探测你的 PATH。

自动安装依赖

extension dev 和 extension build 会在编译之前先装上缺失的依赖。这次安装走的是被检测到的那个管理器,并且会传入 --ignore-scripts。因此依赖里的 postinstall 脚本不会在这一步运行。

注意事项

  • Bun.file 这类 Bun 专有的运行时 API 不属于扩展代码。那些代码是跑在浏览器里的。
  • Extension.js 不会写任何 Bun 专有的脚本。dev、build 和 preview 脚本对每个管理器都一样。
  • 你通过 extension create 引入的模板不带锁文件。Extension.js 会从中剥掉 bun.lock 和 bun.lockb。之后由你自己那次安装来决定依赖树。

下一步