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

​
前置条件

​
启用脚本执行

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

​
系统依赖

Bun v1.1 或更高版本。构建过程使用 Bun 运行其自身的代码生成器。
Visual Studio，并安装“使用 C++ 的桌面开发”工作负载。安装过程中，如果尚未安装适用于 Windows 的 Git，也请一并安装。 使用图形化向导安装 Visual Studio，或通过 WinGet 安装：
安装 Visual Studio 后，需要安装以下工具：
  • LLVM 23.1.1
  • Go
  • Rust（通过 rustup）
  • NASM
  • Perl
  • Ruby
  • Node.js
rustup 会在首次构建时安装 rust-toolchain.toml 中固定的 Rust nightly 工具链。
使用 Scoop 来安装这些剩余工具。
Scoop (x64)
对于 Windows ARM64，请直接从 GitHub releases 下载 LLVM 23.1.1：
ARM64
不要使用 WinGet 或其他包管理器安装这些工具：你很可能会获得 Strawberry Perl，而不是更精简的 Perl 安装。Strawberry Perl 会向 $Env:PATH 添加许多其他实用工具，这些工具会与 MSVC 冲突并导致构建失败。
若要在本地构建 WebKit（可选，仅限 x64），请安装以下软件包：
Scoop
ARM64 构建不需要 Cygwin，因为 WebKit 以预构建二进制文件的形式提供。
从现在开始，请使用已加载 .\scripts\vs-shell.ps1 的 PowerShell 终端。运行以下命令加载该脚本：
要进行验证，请检查 mt.exe 等仅限 MSVC 的命令：
避免将 ninja / cmake 安装到全局路径中：否则你可能会在未加载 .\scripts\vs-shell.ps1 的情况下构建 Bun。

​
构建

成功构建后，会将 bun-debug.exe 写入 build/debug 文件夹。
将此文件夹添加到 $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 实例中运行每个测试文件，因此测试运行器崩溃不会导致整个套件停止。

​
故障排查

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

​
构建

输出文件位于 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 寄存器。