static-php-cli/docs/zh/guide/cli-reference.md

outline

outline
deep

命令行参考

::: 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.4）
--prefer-binary	-p	优先使用预编译二进制
--prefer-source		优先使用源码包
--source-only		仅下载源码制品
--binary-only		仅下载二进制制品
--parallel=<n>	-P	并行下载数（默认 1）
--retry=<n>	-R	失败重试次数（默认 0）
--ignore-cache=<list>		强制重新下载指定制品
--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.4

# 下载指定制品
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	-L / -E	同时解析并安装建议包
--with-packages=<list>		额外安装的包
--no-download		跳过下载步骤（使用已有缓存）
--with-added-patch=<file>	-P	注入外部 PHP 补丁脚本（可重复使用）
--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）

下载透传选项

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

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

示例

# 构建 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

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 程序，或手动检查构建环境。