安装 StaticPHP

系统要求

平台	架构	说明
Linux	x86_64、aarch64	支持主流发行版（Alpine、Debian/Ubuntu、RHEL/CentOS 等）
macOS	x86_64 (Intel)、arm64 (Apple Silicon)	需要 macOS 12 或更高版本
Windows	x86_64	需要 Windows 10 Build 17063 或更高版本

::: tip Linux 下，glibc 环境（Debian、Ubuntu、Arch 等）和 musl 环境（Alpine）均受支持。 doctor 命令会自动检测当前环境并在必要时引导安装合适的工具链。 :::

StaticPHP 有多种安装方式，选择适合你的场景：

spc 无须任何依赖，下载即可运行，支持 Linux、macOS 和 Windows。

spc 本身是由 StaticPHP 构建的静态 PHP 二进制，幽默地说：我们用 StaticPHP 构建了 StaticPHP 的构建工具。

::: code-group

curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64 -o spc

curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-aarch64 -o spc

curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-x86_64 -o spc

curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-macos-aarch64 -o spc

curl.exe -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x86_64.exe -o spc.exe

:::

*nix 系统下载完成后需要赋予可执行权限：

chmod +x spc && ./spc --version

适合想参与开发、或需要修改核心注册表和构建脚本的开发者。需要系统已安装 PHP >= 8.4、Composer，以及 mbstring,posix,pcntl,iconv,phar,zlib 扩展。

git clone https://github.com/crazywhalecc/static-php-cli.git --branch v3
cd static-php-cli
composer install

如果系统还没有 PHP 和 Composer，可以用内置脚本一键安装运行环境：

::: code-group

bin/setup-runtime

.\bin\setup-runtime.ps1
.\bin\setup-runtime.ps1 add-path   # 将 runtime/ 加入 PATH

:::

脚本执行完成后，会在项目目录下生成 runtime/ 子目录，其中包含 php 和 composer 两个可执行文件。安装完成后有两种使用方式：

直接通过路径调用（无需修改环境变量）：

runtime/php bin/spc --help
runtime/php runtime/composer install

将 runtime/ 加入 PATH（之后可直接使用 php、composer、bin/spc）：

export PATH="/path/to/static-php/runtime:$PATH"
# 建议写入 ~/.bashrc 或 ~/.zshrc 使其永久生效

适合在已有 PHP 项目中直接集成 StaticPHP 能力，或通过自定义 registry 支持私有库和扩展的构建。

composer require crazywhalecc/static-php-cli

Vendor 模式的详细用法见扩展 StaticPHP。

Vendor 模式用户可跳过此步骤。

安装完成后，运行 doctor 检查系统构建工具链是否就绪（cmake、make、编译器等）：

# 使用 spc 二进制
./spc doctor
# 使用源码安装
bin/spc doctor

如有缺失，--auto-fix 会尝试自动安装修复：

./spc doctor --auto-fix

检查通过后，继续阅读第一次构建。