Skip to main content
本文档介绍了在 Windows 上的构建流程。如果您遇到问题，请加入我们的 Discord #contributing 频道 寻求帮助。 强烈建议使用 PowerShell 7（pwsh.exe），而非默认的 powershell.exe。

​
前置条件

​
启用脚本执行

默认情况下，运行未验证脚本会被阻止。 
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

​
系统依赖

Bun 版本需为 v1.1 或更高。我们使用 Bun 来运行它自身的代码生成器。 
irm bun.sh/install.ps1 | iex
安装带有“使用 C++ 的桌面开发”工作负载的 Visual Studio。安装时请确保同时安装 Git（若系统尚未安装 Git for Windows）。 Visual Studio 可以通过向导图形界面安装，或用 WinGet 命令安装： 
winget install "Visual Studio Community 2022" --override "--add Microsoft.VisualStudio.Workload.NativeDesktop Microsoft.VisualStudio.Component.Git " -s msstore
安装 Visual Studio 后，需要安装以下工具：
  • LLVM 21.1.8
  • Go
  • Rust（通过 rustup）
  • NASM
  • Perl
  • Ruby
  • Node.js
rust-toolchain.toml 中固定的 Rust nightly 工具链会在首次构建时由 rustup 自动安装。
使用 Scoop 来安装这些剩余工具。
Scoop (x64)
irm https://get.scoop.sh | iex
scoop install nodejs-lts go rustup nasm ruby perl ccache
# scoop 在同时安装 llvm 和其他工具时似乎存在 bug
scoop install [email protected]
对于 Windows ARM64，请直接从 GitHub 发布页面下载 LLVM 21.1.8（这是首个包含 ARM64 Windows 构建的版本）：
ARM64
# 下载并安装 ARM64 的 LLVM
Invoke-WebRequest -Uri "https://github.com/llvm/llvm-project/releases/download/llvmorg-21.1.8/LLVM-21.1.8-woa64.exe" -OutFile "$env:TEMP\LLVM-21.1.8-woa64.exe"
Start-Process -FilePath "$env:TEMP\LLVM-21.1.8-woa64.exe" -ArgumentList "/S" -Wait
请勿使用 WinGet 或其他包管理器安装这些工具，因为您可能会安装 Strawberry Perl，而不是更轻量的 Perl 版本。Strawberry Perl 会安装许多其他工具到 $Env:PATH，这些工具会与 MSVC 冲突并导致构建失败。
如果你打算在本地构建 WebKit（可选，仅限 x64），你应该安装以下软件包：
Scoop
scoop install make cygwin python
ARM64 构建不需要 Cygwin，因为 WebKit 已作为预编译二进制文件提供。
从此处开始，建议您使用已加载 .\scripts\vs-shell.ps1 的 PowerShell 终端。该脚本可在 Bun 仓库中找到，并可通过执行以下命令加载： 
.\scripts\vs-shell.ps1
您可以通过检测一个 MSVC 专用命令行工具（比如 mt.exe）来验证是否正确加载： 
Get-Command mt
不建议将 ninja 或 cmake 安装到全局路径中，因为您可能会在未加载 .\scripts\vs-shell.ps1 的情况下构建 Bun，导致构建失败。

​
构建

bun run build

# 首次运行完成后，可以用下面命令构建
ninja -Cbuild/debug
如果成功，您会在 build/debug 文件夹中看到 bun-debug.exe。 
.\build\debug\bun-debug.exe --revision
建议将此路径加入 $Env:PATH。最简便的办法是打开开始菜单，输入“Path”，然后进入环境变量菜单，将 C:\.....\bun\build\debug 添加到用户环境变量 PATH。之后重启编辑器（如果依旧未更新，则注销后重新登录）。

​
额外路径

  • WebKit 已提取到 build/debug/cache/webkit/

​
测试

您可以使用 bun test <路径> 或封装脚本 bun node:test <路径> 运行测试套件。bun node:test 命令会在独立的 bun.exe 实例中运行每个测试文件，防止测试运行器崩溃影响整个测试套件。 
# 安装依赖
bun i --cwd packages\bun-internal-test

# 运行完整测试套件并带有报告器
# 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 已打开，就无法覆盖它。您很可能有一个正在运行的实例，也许是在 vscode 调试器中？

​
从 Linux 交叉编译

Windows 二进制文件（x64 和 arm64）也可以在 Linux 主机上构建。该构建使用主机 LLVM 提供的 clang-cl、lld-link、llvm-lib 和 llvm-rc——它们是每个 LLVM 发行版的一部分——再加上一个用于头文件和导入库的 MSVC CRT/STL 与 Windows SDK 的 “xwin splat”。

​
前置条件

  1. 与原生构建使用的相同 LLVM 版本（参见 scripts/bootstrap.sh 中的 llvm_version_exact），并确保可使用 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，其中包含按 Visual Studio 安装布局展开的 MSVC CRT、Windows SDK 和 ATL。请注意，下载这些组件意味着您同意 Microsoft 适用于它们的许可条款。
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；如果放在其他位置，请设置 WINDOWS_SYSROOT=<path> 或传入 --winsysroot=<path>（使用可由用户写入的路径也能让 configure 为您管理这些别名）。configure 会在每次交叉构建开始时验证该 splat。CI 代理会将相同的 splat 烘焙到它们的镜像中（.buildkite/Dockerfile、scripts/bootstrap.sh）；当某个代理没有该 splat 时，构建会在 configure 时将其下载到缓存目录中。

​
构建

# 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，CI 的 Windows x64 交叉构建通道默认启用它。若在本地使用，则需要显式开启： 
bun run build --profile=windows-x64-release --lto=on
这会用 -flto=thin 编译 bun 的 C/C++，让 rustc 输出 LLVM bitcode（-Clinker-plugin-lto），拉取 bun-webkit-windows-amd64-lto 的 ThinLTO 预构建产物，并使用 rustc 自带的 lld-link 将所有内容链接起来（其 LLVM 足够新，能够读取两个编译器生成的 bitcode）。arm64 不支持 LTO（没有 -lto 的 WebKit 预构建产物——LLVM 的 CodeView emitter 在 LTO 代码生成期间无法处理 ARM64 NEON tuple 寄存器），--baseline 也不支持。