命令行参考

TIP

如果你采用的是 spc 二进制方式安装，请将本章节中的所有 spc 替换为 ./spc 或 .\spc.exe。

如果你采用的是源码安装，请将 spc 替换为 bin/spc。

download

下载构建所需的源码包和预编译二进制。

spc download [artifacts] [options]

artifacts（可选）：指定要下载的制品名称，逗号分隔（如 "php-src,openssl,curl"）。

选项

选项	缩写	说明
--for-extensions=<list>	-e	按扩展名下载其所需的制品
--for-libs=<list>	-l	按库名下载其所需的制品
--for-packages=<list>		按包名下载其所需的制品
--without-suggests		使用 --for-extensions 时跳过建议包
--clean		下载前删除旧的下载缓存
--with-php=<ver>		PHP 版本，格式为 major.minor（默认 8.5）
--prefer-binary	-p	优先使用预编译二进制
--prefer-source		优先使用源码包
--source-only		仅下载源码制品
--binary-only		仅下载二进制制品
--parallel=<n>	-P	并行下载数（默认 1）
--retry=<n>	-R	失败重试次数（默认 0）
--ignore-cache=<list>	-i	强制重新下载指定制品
--no-alt		不使用镜像站
--no-shallow-clone		不使用浅层克隆
--custom-url=<src:url>	-U	覆盖指定源的下载地址
--custom-git=<src:branch:url>	-G	覆盖为自定义 git 仓库
--custom-local=<src:path>	-L	使用本地路径作为制品来源

示例

# 按扩展名下载（推荐）
spc download --for-extensions="bcmath,openssl,curl" --with-php=8.5

# 下载指定制品
spc download "php-src,openssl"

# 增加并行数和重试次数
spc download --for-extensions="bcmath,openssl,curl" --parallel 8 --retry=3

# 优先使用预编译二进制
spc download --for-extensions="bcmath,openssl,curl" --prefer-binary

# 强制重新下载 PHP 源码（如切换版本）
spc download --for-extensions="bcmath,curl" --ignore-cache="php-src" --with-php=8.3

# 覆盖下载地址
spc download --for-extensions="bcmath" --custom-url "php-src:https://downloads.php.net/~user/php-8.5.0alpha1.tar.xz"

build:php

从源码编译 PHP 及扩展。别名：build。

spc build:php <extensions> [options]

extensions（必填）：要静态编译的扩展名列表，逗号分隔（如 "bcmath,openssl,curl"）。

build:php 上也可使用所有 download 选项，只需加上 --dl- 前缀（如 --dl-with-php=8.3、--dl-parallel=4），这些参数将传递给构建前自动运行的下载器。

SAPI 选择

以下选项仅适用于 build:php 组合目标。如需单独构建某个 SAPI，请使用对应的专用命令（如 spc build:php-cli）。

选项	说明
--build-cli	构建 cli SAPI（php / php.exe）
--build-fpm	构建 php-fpm（仅 Linux 和 macOS）
--build-cgi	构建 php-cgi
--build-micro	构建 micro.sfx
--build-embed	构建 embed 静态库（libphp.a / php8embed.lib）
--build-frankenphp	构建 FrankenPHP 二进制

通用构建选项

选项	缩写	说明
--no-strip		保留调试符号，不精简二进制
--with-upx-pack		用 UPX 压缩产物（需先 spc install-pkg upx；仅 Linux 和 Windows）
--disable-opcache-jit		禁用 OPcache JIT
--with-config-file-path=<path>		PHP 查找 php.ini 的目录（默认：/usr/local/etc/php）
--with-config-file-scan-dir=<path>		PHP 扫描追加 .ini 文件的目录（默认：/usr/local/etc/php/conf.d）
--with-hardcoded-ini=<k=v>	-I	编译时将 INI 配置硬编码进二进制（可重复使用）
--enable-zts		启用线程安全（ZTS）模式
--no-smoke-test		跳过构建后的冒烟测试
--with-suggests		同时解析并安装建议包
--with-packages=<list>		额外安装的包
--no-download		跳过下载步骤（使用已有缓存）
--build-shared=<list>	-D	指定编译为共享 .so / .dll 的扩展

micro 专用选项

选项	说明
--with-micro-fake-cli	让 micro 的 PHP_SAPI 报告为 cli 而非 micro
--without-micro-ext-test	跳过构建后的 micro.sfx 扩展测试
--with-micro-logo=<path>	为 micro.sfx 嵌入自定义 .ico 图标（仅 Windows）
--enable-micro-win32	将 micro.sfx 构建为 Win32 GUI 程序而非控制台程序（仅 Windows）

frankenphp 专用选项

选项	说明
--enable-zts	FrankenPHP 必须开启线程安全
--with-frankenphp-app=<path>	将指定目录嵌入到 FrankenPHP 二进制中

embed 专用选项

选项	说明
--build-shared=<list>	将指定扩展编译为共享库（需要 embed SAPI）
--maintainer-skip-build	（仅维护者）若 buildroot 中已存在 libphp.a / libphp.so，则跳过 PHP embed 的编译构建

下载透传选项

所有下载器选项均可加 --dl- 前缀使用：

选项	说明
--dl-with-php=<ver>	指定下载的 PHP 版本（默认 8.5）
--dl-prefer-binary	优先使用预编译二进制依赖
--dl-parallel=<n>	并行下载数
--dl-retry=<n>	失败重试次数
--dl-custom-url=<src:url>	覆盖指定源的下载地址
--dl-custom-git=<src:branch:url>	覆盖为自定义 git 仓库

Downloader 选项传递给 build:php 命令时，会被自动下载器在构建前使用。 这样你就可以直接通过构建命令控制下载行为，无需单独执行 spc download 命令。

spc build:php "bcmath,openssl,curl" --build-cli --dl-with-php=8.3 --dl-prefer-binary --dl-parallel=4

示例

# 构建 cli SAPI
spc build:php "bcmath,openssl,curl" --build-cli

# 同时构建 cli + micro
spc build:php "bcmath,phar,openssl,curl" --build-cli --build-micro

# 指定 PHP 版本
spc build:php "bcmath,openssl" --build-cli --dl-with-php=8.3

# 硬编码 INI 到二进制
spc build:php "bcmath,pcntl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"

# 保留调试符号
spc build:php "bcmath,openssl" --build-cli --no-strip

# 构建 FrankenPHP（需开启 ZTS）
spc build:php "bcmath,openssl,curl" --build-frankenphp --enable-zts

build:php-cli, build:php-fpm, build:php-micro, build:php-embed, build:php-cgi, build:frankenphp

专用单目标构建命令，接受与 build:php 相同的选项，但不需要 SAPI 选择标志（--build-*），目标已隐式确定。

spc build:php-cli "bcmath,openssl,curl"
spc build:php-micro "bcmath,phar,openssl"
spc build:php-fpm "bcmath,openssl,curl,pdo_mysql"
spc build:php-embed "bcmath,openssl"
spc build:frankenphp "bcmath,openssl,curl" --enable-zts

build:libs

从源码构建一个或多个库包。

spc build:libs <libraries> [options]

libraries（必填）：要构建的库包名称列表，逗号分隔（如 "openssl,curl,zlib"）。

支持所有 download 命令的选项，加 --dl- 前缀传递。

选项

选项	缩写	说明
--with-suggests	-L、-E	同时解析并安装建议包
--with-packages=<list>		额外安装的包，逗号分隔
--no-download		跳过下载步骤（使用已有缓存）

示例

# 构建单个库
spc build:libs openssl

# 构建多个库
spc build:libs "openssl,curl,zlib"

# 构建时包含建议包
spc build:libs openssl --with-suggests

# 跳过下载步骤
spc build:libs openssl --no-download

craft

读取 craft.yml 并自动完成全流程构建。

spc craft [path/to/craft.yml]

未指定路径时，使用当前工作目录下的 craft.yml。配置格式参见 craft.yml 配置。

doctor

检查当前环境是否满足编译要求。

spc doctor [--auto-fix[=never]]

选项	说明
--auto-fix	自动修复检测到的问题（使用系统包管理器）
--auto-fix=never	仅报告问题，不尝试自动修复

dev:shell

进入加载了 StaticPHP 构建环境的交互式 Shell（编译器 wrapper、buildroot/、pkgroot/ 等均已添加到 PATH）。

spc dev:shell

可用于在 embed SAPI 的 libphp.a 上编译小型 C 程序，或手动检查构建环境。

check-update

检查指定制品是否有可用更新。

spc check-update [artifact] [options]

artifact（可选）：要检查更新的制品名称，逗号分隔。默认检查所有已下载的制品。

选项

选项	缩写	说明
--json		以 JSON 格式输出结果
--bare		检查时不要求制品已下载（旧版本显示为 null）
--parallel=<n>	-p	并行检查数（默认 10）
--with-php=<ver>		PHP 版本上下文，格式为 major.minor（默认 8.5）

示例

# 检查所有已下载制品
spc check-update

# 检查指定制品
spc check-update "openssl,curl"

# 以 JSON 格式输出
spc check-update --json

# 无需先下载即可检查
spc check-update "openssl" --bare

dump-extensions

从 Composer 项目中分析所需的 PHP 扩展列表。

spc dump-extensions [path] [options]

path（可选）：项目根目录路径，默认为当前目录（.）。

选项

选项	缩写	说明
--format=<fmt>	-F	输出格式（默认 default）
--no-ext-output=<list>	-N	未找到扩展时输出的默认组合（逗号分隔），而不是以失败退出
--no-dev		不包含 dev 依赖
--no-spc-filter	-S	不使用 SPC 过滤器筛选扩展

示例

# 分析当前目录的 Composer 项目
spc dump-extensions

# 分析指定目录
spc dump-extensions /path/to/project

# 不包含 dev 依赖
spc dump-extensions --no-dev

# 未找到扩展时输出默认组合
spc dump-extensions --no-ext-output="bcmath,openssl"

dump-license

导出制品的开源许可证文件。

spc dump-license [artifacts] [options]

artifacts（可选）：要导出许可证的制品名称，逗号分隔（如 "php-src,openssl,curl"）。

选项

选项	缩写	说明
--for-extensions=<list>	-e	按扩展名导出（自动包含 php-src），如 "openssl,mbstring"
--for-libs=<list>	-l	按库名导出，如 "openssl,zlib"
--for-packages=<list>	-p	按包名导出，如 "php,libssl"
--dump-dir=<path>	-d	许可证输出目录（默认 buildroot/license）
--without-suggests		不包含建议包的许可证

示例

# 按扩展名导出许可证
spc dump-license --for-extensions="bcmath,openssl,curl"

# 导出指定制品的许可证
spc dump-license "php-src,openssl"

# 指定输出目录
spc dump-license --for-extensions="bcmath,openssl" --dump-dir=/tmp/licenses

extract

将已下载的制品解压到对应的目标位置。

spc extract [artifacts] [options]

artifacts（可选）：要解压的制品名称，逗号分隔（如 "php-src,openssl,curl"）。

选项

选项	缩写	说明
--for-extensions=<list>	-e	按扩展名解压所需制品，如 "openssl,mbstring"
--for-libs=<list>	-l	按库名解压所需制品，如 "libcares,openssl"
--for-packages=<list>		按包名解压所需制品，如 "php,libssl,libcurl"
--without-suggests		使用 --for-extensions 时跳过建议包
--source-only		强制解压源码，即使已有预编译二进制

示例

# 按扩展名解压
spc extract --for-extensions="bcmath,openssl,curl"

# 解压指定制品
spc extract "php-src,openssl"

# 强制解压源码
spc extract --for-extensions="bcmath,openssl" --source-only

install-pkg

安装额外的辅助包（如 UPX、工具链等）。别名：i、install-package。

spc install-pkg <package> [options]

package（必填）：要安装的包名称。

支持所有 download 命令的选项，加 --dl- 前缀传递。

示例

# 安装 UPX 压缩工具
spc install-pkg upx

micro:combine

将 micro.sfx 与 PHP/PHAR 文件合并为独立可执行文件。

spc micro:combine <file> [options]

file（必填）：要合并的 PHP 或 PHAR 文件路径。

选项

选项	缩写	说明
--with-micro=<path>	-M	指定自定义 micro.sfx 文件路径（默认使用 buildroot/bin/micro.sfx）
--with-ini-set=<k=v>	-I	合并时注入 INI 配置（可重复使用）
--with-ini-file=<path>	-N	合并时注入 INI 文件
--output=<name>	-O	自定义输出文件名（默认 my-app）

示例

# 合并 PHP 文件
spc micro:combine app.php

# 合并 PHAR 文件并指定输出名
spc micro:combine app.phar --output my-app

# 注入 INI 配置
spc micro:combine app.php -I "memory_limit=512M" -I "disable_functions=system"

# 注入 INI 文件
spc micro:combine app.php --with-ini-file=custom.ini

# 使用自定义 micro.sfx
spc micro:combine app.php --with-micro=/path/to/micro.sfx

reset

清理构建目录，重置构建环境。

spc reset [options]

默认清理 buildroot/ 和 source/ 目录。

选项

选项	缩写	说明
--with-pkgroot		同时删除 pkgroot/ 目录
--with-download		同时删除 downloads/ 目录
--yes	-y	跳过确认提示

示例

# 清理构建目录（会提示确认）
spc reset

# 同时清理下载缓存
spc reset --with-download

# 完全清理（不提示）
spc reset --with-pkgroot --with-download --yes

spc-config

输出静态编译所需的编译器和链接器标志，适用于将 PHP embed 库链接到自定义程序。

spc spc-config [extensions] [options]

extensions（可选）：要包含的扩展名列表，逗号分隔。

选项

选项	缩写	说明
--with-libs=<list>		额外包含的库，逗号分隔
--with-packages=<list>	-p	额外包含的包，逗号分隔
--with-suggested-libs	-L	包含建议库
--with-suggests		包含所有建议包
--with-suggested-exts	-E	包含建议扩展
--includes		仅输出 -I 头文件路径（CFLAGS）
--libs		仅输出 -L 和 -l 链接标志（LDFLAGS + LIBS）
--libs-only-deps		仅输出依赖库的 -l 标志
--absolute-libs		使用库文件的绝对路径输出
--no-php		不链接 PHP 库

示例

# 输出完整编译标志
spc spc-config "bcmath,openssl,curl"

# 仅输出头文件路径
spc spc-config "bcmath,openssl" --includes

# 仅输出链接标志
spc spc-config "bcmath,openssl" --libs

# 使用绝对路径
spc spc-config "bcmath,openssl" --libs --absolute-libs