第一次构建
本页通过完整的示例演示如何从零开始构建一个静态 PHP 二进制。
TIP
如果你采用的是 spc 二进制方式安装，请将本章节中的所有 spc 替换为 ./spc 或 .\spc.exe。
如果你采用的是源码安装，请将 spc 替换为 bin/spc。
两种构建方式
StaticPHP 提供两种构建方式，根据使用场景选择：
| 方式 | 适合场景 |
|---|---|
craft 一键构建 | 日常使用、快速上手 |
| 分步构建 | 细化构建流程 |
方式一：craft 一键构建（推荐）
craft 命令读取一个 craft.yml 配置文件，自动完成依赖下载、库编译、PHP 构建的全流程。
编写 craft.yml
在当前目录创建 craft.yml，声明要编译的 PHP 版本、扩展和目标 SAPI：
php-version: 8.5
extensions: bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer
sapi:
- cli
- micro不想手动编写？试试命令行生成器自动生成配置。
开始构建
spc craft构建过程依次执行：下载依赖 → 编译依赖库 → 编译 PHP。全程无需人工干预。
如需查看详细日志，加上 -v、-vv 或 -vvv 参数：
spc craft -v查看产物
构建成功后，产物均位于 buildroot/bin/：
| SAPI | 产物路径 |
|---|---|
| cli | buildroot/bin/php（Windows：buildroot/bin/php.exe） |
| fpm | buildroot/bin/php-fpm |
| micro | buildroot/bin/micro.sfx |
| embed | buildroot/lib/libphp.a |
| frankenphp | buildroot/bin/frankenphp |
验证一下 cli 是否可用：
./buildroot/bin/php -v
./buildroot/bin/php -m方式二：分步构建
分步方式适合需要将下载与编译拆分为独立阶段的场景，例如在 CI 中缓存下载内容以加速后续构建。
第一步：下载依赖
v3 版本中，你可以省略这一步骤，直接构建想要的内容，StaticPHP 会自动下载所需的依赖库和扩展源码。
但如果你想提前下载，或在网络环境较差的情况下分阶段构建，可以使用 download 命令：
# 按扩展列表下载（推荐，只下载实际需要的内容）
spc download --for-extensions="bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer" --with-php=8.5
# 按依赖包列表下载
spc download "curl,openssl" --with-php=8.5下载内容缓存在 downloads/ 目录，重复构建时会直接复用。
# 网络较慢时，可增大并发数和重试次数
spc download --for-extensions="bcmath,openssl,curl" --parallel 10 --retry=3
# 优先使用预编译的二进制依赖，跳过源码编译（大幅加速构建）
spc download --for-extensions="bcmath,openssl,curl" --prefer-binary第二步：构建 PHP
# 构建 cli SAPI
spc build:php "bcmath,phar,zlib,openssl,curl,fileinfo,tokenizer" --build-cli
# 同时构建多个 SAPI
spc build:php "bcmath,phar,zlib,openssl,curl" --build-cli --build-micro常用构建选项
| 选项 | 说明 |
|---|---|
--build-cli | 构建 cli SAPI |
--build-fpm | 构建 php-fpm（不支持 Windows） |
--build-micro | 构建 micro.sfx |
--build-embed | 构建嵌入式 SAPI |
--build-frankenphp | 构建 FrankenPHP |
--enable-zts | 启用线程安全（ZTS）版本 |
--no-strip | 保留调试符号，不精简二进制 |
-I key=value | 硬编译 INI 选项到 PHP 中 |
--with-upx-pack | 用 UPX 压缩产物（需先 spc install-pkg upx） |
硬编译 INI 的例子——预设更大的内存限制，并禁用 system 函数：
spc build:php "bcmath,pcntl,posix" --build-cli -I "memory_limit=4G" -I "disable_functions=system"打包 micro 应用
构建 micro.sfx 后，用 micro:combine 将你的 PHP 代码打包进去，生成一个完全独立的可执行文件：
echo "<?php echo 'Hello, World!' . PHP_EOL;" > hello.php
spc micro:combine hello.php --output=hello
./hello也支持打包 .phar 文件，以及注入 INI 配置：
# 打包 phar
spc micro:combine your-app.phar --output=your-app
# 打包时注入 INI
spc micro:combine your-app.phar --output=your-app -I "memory_limit=512M"
# 从 ini 文件注入配置
spc micro:combine your-app.phar --output=your-app -N /path/to/custom.ini调试与重新构建
构建失败，或想查看详细过程，使用 -v / -vv / -vvv：
-v将显示INFO级别的日志，包含执行到的模块和执行的编译命令等。-vv将显示DEBUG级别的日志，包含所有 StaticPHP 中调试级别的日志。-vvv将显示DEBUG级别的日志，并将其他 shell 命令执行的 STDOUT 输出到终端。
spc build:php "bcmath,openssl" --build-cli -vv或者，你也可以查看 log/spc.shell.log 和 log/spc.output.log 获取终端输出和 StaticPHP 日志。
如需清理编译中间产物、从头重新构建（不重新下载），使用 reset：
spc reset
# 然后重新构建
spc build:php "bcmath,openssl" --build-cliTIP
reset 只清理 buildroot/ 和 source/ 目录，不会删除 downloads/ 缓存。 如需同时清理下载缓存，加上 --with-download 参数。
如果问题持续无法解决，欢迎提交 Issue，并附上 craft.yml（如有）和 log/ 目录的压缩包。
接下来
- PHP SAPI 构建参考 - 各个 PHP 的 SAPI 构建及使用指南
- 命令行参考 — 所有命令与选项的完整说明
- 扩展列表 — 查看支持的扩展及其依赖关系
- 常见问题 — 构建失败时的排查指南