> ## Documentation Index
> Fetch the complete documentation index at: https://bun.ll1025.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 Windows 上构建

> 在 Windows 上构建 Bun

使用 [PowerShell 7 (`pwsh.exe`)](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4) 而不是默认的 `powershell.exe`。如遇到问题，请在我们的 [Discord 的 #contributing 频道](http://bun.com/discord)中提问。

## 前置条件

### 启用脚本执行

默认情况下，运行未验证的脚本是被阻止的。

```ps1 theme={null}
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted
```

### 系统依赖

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

```ps1 theme={null}
irm bun.sh/install.ps1 | iex
```

[Visual Studio](https://visualstudio.microsoft.com)，包含"使用 C++ 的桌面开发"工作负载。在安装过程中，如果尚未安装 Git for Windows，也请安装 Git。

通过图形向导或 WinGet 安装 Visual Studio：

```ps1 theme={null}
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

<Note>rustup 会在首次构建时安装 `rust-toolchain.toml` 中指定的 Rust 夜间工具链。</Note>

使用 [Scoop](https://scoop.sh) 安装其余工具。

```ps1 Scoop (x64) theme={null}
irm https://get.scoop.sh | iex
scoop install nodejs-lts go rustup nasm ruby perl ccache
# scoop 如果同时安装 llvm 和其他工具似乎有 bug
scoop install llvm@21.1.8
```

对于 Windows ARM64，直接从 GitHub 发布页面下载 LLVM 21.1.8（首个提供 ARM64 Windows 构建的版本）：

```ps1 ARM64 theme={null}
# 下载并安装 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
```

<Note>
  不要使用 WinGet 或其他包管理器安装这些工具：你很可能得到的是 Strawberry Perl，而不是更精简的 Perl 安装。Strawberry Perl 会将许多其他工具添加到 `$Env:PATH` 中，这些工具会与 MSVC 冲突并导致构建失败。
</Note>

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

```ps1 Scoop theme={null}
scoop install make cygwin python
```

<Note>ARM64 构建不需要 Cygwin，因为 WebKit 以预编译二进制形式提供。</Note>

接下来的步骤，**使用已加载 `.\scripts\vs-shell.ps1` 的 PowerShell 终端**。运行脚本来加载它：

```ps1 theme={null}
.\scripts\vs-shell.ps1
```

要验证，检查是否有仅 MSVC 可用的命令，如 `mt.exe`：

```ps1 theme={null}
Get-Command mt
```

<Note>
  避免将 `ninja` / `cmake` 安装到全局路径：你可能会在没有加载 `.\scripts\vs-shell.ps1` 的情况下构建 Bun。
</Note>

## 构建

```ps1 theme={null}
bun run build

# 首次 `bun run build` 后，可以使用以下命令进行构建
ninja -Cbuild/debug
```

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

```ps1 theme={null}
.\build\debug\bun-debug.exe --revision
```

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

## 额外路径

* WebKit 解压到 `build/debug/cache/webkit/`

## 测试

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

```ps1 theme={null}
# 运行整个测试套件，带报告器
# 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/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：MSVC CRT、Windows SDK 和 ATL 的 [xwin](https://github.com/Jake-Shadle/xwin) splat，布局类似 Visual Studio 安装。下载这些组件意味着你接受微软对它们的许可条款。

```bash theme={null}
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 时将其获取到缓存目录中。

### 构建

```bash theme={null}
# 调试构建
bun run build --profile=windows-x64
bun run build --profile=windows-arm64

# 发布构建
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 发布交叉构建支持带跨语言（Rust↔C++）LTO 的 ThinLTO。这是可选的：

```bash theme={null}
bun run build --profile=windows-x64-release --lto=on
```

`--lto=on` 使用 `-flto=thin` 编译 Bun 的 C/C++，使 rustc 发出 LLVM 位码（`-Clinker-plugin-lto`），拉取 `bun-webkit-windows-amd64-lto` ThinLTO 预构建，并使用 rustc 附带的 `lld-link` 链接所有内容（其 LLVM 版本足够新，可以读取两个编译器的位码）。arm64 没有 LTO（没有 `-lto` WebKit 预构建：LLVM 的 CodeView 发射器在 LTO 代码生成期间无法处理 ARM64 NEON 元组寄存器），`--baseline` 也没有。