简体中文
选择语言
简体中文Simplified Chinese繁體中文Traditional ChineseEnglishEnglish
安装 Bunv1.4.4
运行时包管理器打包器测试运行器代码检查格式化指南参考博客反馈

在 Windows 上构建

在 Windows 上构建 Bun

请使用 PowerShell 7 (pwsh.exe)，而不是默认的 powershell.exe。如果遇到问题，请在我们的 Discord 上的 #contributing 频道 中提问。

前置条件

启用脚本执行

默认情况下，禁止运行未经验证的脚本。

PowerShell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

系统依赖

Bun v1.1 或更高版本。构建过程使用 Bun 运行其自身的代码生成器。

PowerShell
irm bun.sh/install.ps1 | iex

Visual Studio，并安装“使用 C++ 的桌面开发”工作负载。安装过程中，如果尚未安装适用于 Windows 的 Git，也请一并安装。

使用图形化向导安装 Visual Studio，或通过 WinGet 安装：

PowerShell
winget install "Visual Studio Community 2022" --override "--add Microsoft.VisualStudio.Workload.NativeDesktop Microsoft.VisualStudio.Component.Git " -s msstore

安装 Visual Studio 后，需要安装以下工具：

  • LLVM 23.1.1
  • Go
  • Rust（通过 rustup）
  • NASM
  • Perl
  • Ruby
  • Node.js

使用 Scoop 来安装这些剩余工具。

Scoop
irm https://get.scoop.sh | iex
scoop install nodejs-lts go rustup nasm ruby perl ccache
# scoop seems to be buggy if you install llvm and the rest at the same time
scoop install llvm@23.1.1

对于 Windows ARM64，请直接从 GitHub releases 下载 LLVM 23.1.1：

ARM64
# Download and install LLVM for ARM64
Invoke-WebRequest -Uri "https://github.com/llvm/llvm-project/releases/download/llvmorg-23.1.1/LLVM-23.1.1-woa64.msi" -OutFile "$env:TEMP\LLVM-23.1.1-woa64.msi"
Start-Process msiexec.exe -ArgumentList "/i `"$env:TEMP\LLVM-23.1.1-woa64.msi`" /qn" -Wait

若要在本地构建 WebKit（可选，仅限 x64），请安装以下软件包：

Scoop
scoop install make cygwin python

从现在开始，请使用已加载 .\scripts\vs-shell.ps1 的 PowerShell 终端。运行以下命令加载该脚本：

PowerShell
.\scripts\vs-shell.ps1

要进行验证，请检查 mt.exe 等仅限 MSVC 的命令：

PowerShell
Get-Command mt

构建

PowerShell
bun run build

成功构建后，会将 bun-debug.exe 写入 build/debug 文件夹。

PowerShell
.\build\debug\bun-debug.exe --revision

将此文件夹添加到 $Env:PATH：打开“开始”菜单，输入“Path”，然后使用环境变量菜单，将 C:\.....\bun\build\debug 添加到用户环境变量 PATH 中。然后重新启动编辑器（如果仍未生效，请注销后重新登录）。

额外路径

  • 构建会将 WebKit 解压到 $Env:BUN_INSTALL\build-cache\webkit-<version>-debug（ARM64 上为 webkit-<version>-arm64-debug）；BUN_INSTALL 默认为 ~\.bun。设置 $Env:BUN_BUILD_CACHE_DIR 可将构建缓存放到其他位置。

测试

使用 bun-debug test <path> 或包装脚本 bun run test <path> 运行测试套件。bun run test 命令会在单独的 bun-debug.exe 实例中运行每个测试文件，因此测试运行器崩溃不会导致整个套件停止。

PowerShell
# 使用报告器运行整个测试套件
# package.json 脚本 "test" 默认使用 "build/debug/bun-debug.exe"
bun run test

# 运行单个测试文件：
bun-debug test node\fs
bun-debug test "C:\bun\test\js\bun\resolve\import-meta.test.js"

故障排查

.rc 文件构建失败

llvm-rc.exe 很奇怪；不要使用它。请改用 rc.exe：确保你处于 Visual Studio 开发人员终端中，并检查 rc /?，确认它是 Microsoft Resource Compiler。

输出写入失败 ‘bun-debug.exe’: 权限被拒绝

bun-debug.exe 处于打开状态时无法覆盖它。你可能有一个正在运行的实例，也可能是在 VS Code 调试器中运行。

从 Linux 交叉编译

你也可以在 Linux 主机上构建 Windows 二进制文件（x64 和 arm64）。构建过程使用主机 LLVM 的 clang-cl、lld-link、llvm-lib 和 llvm-rc（这些工具包含在每个 LLVM 发行版中）。对于头文件和导入库，构建还会使用 MSVC CRT/STL 和 Windows SDK 的“xwin splat”。

前置条件

  1. 与原生构建相同版本的 LLVM（scripts/build/ci-images/spec.ts 中的 pins.llvm），并确保 clang-cl、lld-link、llvm-lib 和 llvm-rc 可用。在 Debian/Ubuntu 上，apt.llvm.org 软件包提供这些工具。
  2. nasm（仅 Windows x64 构建需要；BoringSSL 的 x64 汇编采用 NASM 语法）。
  3. Windows 目标的 Rust std（rust-toolchain.toml 中列出了这些目标；如果缺少，可运行 rustup target add x86_64-pc-windows-msvc aarch64-pc-windows-msvc）。
  4. Windows sysroot：一个 xwin splat，其中包含 MSVC CRT、Windows SDK 和 ATL，目录结构与 Visual Studio 安装目录相同。下载这些组件即表示接受 Microsoft 对这些组件的许可条款。
bash
cargo install xwin # 或下载一个发布版二进制文件
xwin --accept-license --arch x86_64,aarch64 --sdk-version 10.0.26100 --crt-version 14.44.17.14 --include-atl splat \
  --use-winsysroot-style --preserve-ms-arch-notation --include-debug-libs \
  --output /opt/winsysroot
# clang-cl/lld-link 将 SDK 路径视为 "Include"/"Lib"；
# splat 会用小写写入这些路径，所以需要把两种拼写都做别名（需要与
# splat 相同的权限——当目录可写时，configure 会自行创建这些别名）。
ln -s include "/opt/winsysroot/Windows Kits/10/Include"
ln -s lib "/opt/winsysroot/Windows Kits/10/Lib"

构建过程会自动在 /opt/winsysroot（或 /opt/xwin）查找 sysroot。如果 sysroot 位于其他位置，请设置 WINDOWS_SYSROOT=<path> 或传入 --winsysroot=<path>。使用用户可写的路径，也可以让 configure 自动管理这些别名。每次交叉构建开始时，configure 都会验证 splat。CI 代理会将相同的 splat 预置到其镜像中（使用 scripts/build/ci-images/spec.ts 中的 windowsSysroot 工具）；如果代理上没有该工具，构建过程会在 configure 时将其下载到缓存目录。

构建

bash
# Debug 构建
bun run build --profile=windows-x64
bun run build --profile=windows-arm64

# Release 构建
bun run build --profile=windows-x64-release
bun run build --profile=windows-arm64-release

输出文件位于 build/debug-windows-x64/bun-debug.exe、build/release-windows-aarch64/bun-profile.exe + bun.exe 等路径中。等效的原始参数为：bun run build --os=windows --arch=aarch64。

构建过程不会在主机上运行交叉编译出的可执行文件（会跳过 --revision 冒烟测试），因此请在 Windows 机器或 Wine 中测试这些文件。

LTO

x64 release 交叉构建使用 ThinLTO，并进行跨语言（Rust↔C++）LTO，与所有 release 构建一样（加上 --lto=off 可加快重新链接）：

  • Bun 的 C/C++ 使用 -flto=thin 进行编译
  • rustc 会生成 LLVM bitcode（-Clinker-plugin-lto）
  • bun-webkit-windows-amd64-lto ThinLTO 预构建版本是被链接的 WebKit
  • 所有内容都使用 LLVM 的 lld-link 进行链接，它会读取两种编译器的 bitcode：构建要求 clang 和 rustc 使用相同的主版本

arm64 不支持 LTO，因为没有 -lto WebKit 预构建版本：LLVM 的 CodeView 发射器在 LTO 代码生成期间无法处理 ARM64 NEON tuple 寄存器。

编辑此页 基于 Bun 官方文档构建 · Bun v1.4.4