Skip to main content

Documentation Index

Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

本文档介绍了在 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 (via 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 调试器中还未关闭。