mirror of
https://github.com/crazywhalecc/static-php-cli.git
synced 2026-07-02 14:25:41 +08:00
17 KiB
17 KiB
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.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