06864fc3f6
- Add msys2-build-essentials target: downloads the MSYS2 nightly sfx,
extracts it, disables PGP keyring (CI-safe), runs two-pass pacman
update, and installs autotools build essentials (make, autoconf,
automake, libtool, pkgconf, perl).
- Add 7za-win target: downloads 7za.exe to PKG_ROOT_PATH\bin.
- Remove php-sdk-binary-tools target and all PHP_SDK_PATH references;
replace with SPC_MSYS2_PATH throughout Artifact, ArtifactExtractor,
FileSystem, DefaultShell and MSVCToolchain.
- Replace {php_sdk_path} path placeholder with {spc_msys2_path}.
- WindowsToolCheck: replace checkSDK/installSDK with checkMsys2,
installMsys2 and check7zaWin/install7zaWin fix items.
- nasm.yml: extract nasm.exe/ndisasm.exe to {pkg_root_path}/bin.
- env.ini: rename PHP_SDK_PATH to SPC_MSYS2_PATH.
- Docs: update Windows migration guide and package-model placeholder docs.
7.9 KiB
从 v2 迁移
StaticPHP v3 是一次完整的重写。核心构建流程（download → build → combine）保持不变，但部分命令、选项和配置字段已发生变化。本页列出了切换前所有需要更新的内容。
::: info 范围说明
本指南仅涵盖面向用户的 CLI 命令、选项、craft.yml 字段和 env.ini 变量名称。不涵盖内部 PHP API。
:::
文档地址变更
官方文档站点已迁移：
- v3 文档（当前）：https://static-php.dev — 主站现在托管 v3 文档。
- v2 文档（归档）：https://static-php.github.io/v2-docs/ — v2 文档已归档保留，供参考。
请更新你保存的书签或内部链接。
spc 二进制下载地址变更
nightly spc 自包含二进制文件已迁移到新路径：
| 地址 | |
|---|---|
| v2 | https://dl.static-php.dev/static-php-cli/spc-bin/nightly/ |
| v3 | https://dl.static-php.dev/v3/spc-bin/nightly/ |
请更新所有直接下载 spc 二进制的 CI 脚本或初始化命令，例如：
# v2
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
# v3
curl -o spc https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64
已移除的命令
| v2 命令 | v3 替代方案 | 说明 |
|---|---|---|
del-download |
spc reset |
reset 支持 --with-pkgroot 和 --with-download 以进行更细粒度的控制 |
del-download --all |
spc reset --with-download |
删除下载缓存目录 |
已移除的选项
--with-added-patch / -P（build 命令）
该选项允许在特定构建阶段注入外部 PHP patch 脚本。v3 已完全移除此功能。
目前没有直接的替代方案。如果你依赖此功能，请考虑以下方式：
- 将你的 patch 贡献到 StaticPHP 的上游仓库。
- 对于项目专用的 patch，可以使用自定义 registry 并编写 Package 类。详情参见编写 Package 类。
::: tip 未来计划 未来版本可能会提供用于轻量级 patch 的单文件 hook API。 :::
Windows 专有：--with-sdk-binary-dir 和 --vs-ver
这两个选项已不再被命令行接受。在 v3 中，php-sdk-binary-tools 依赖已被完全移除。v3 现在通过管理自己的 MSYS2 环境来支持 Windows 上基于 autotools 的库构建。运行 spc doctor --install 即可自动下载并配置 MSYS2。
如需指向自定义 MSYS2 安装目录，请设置 SPC_MSYS2_PATH 环境变量，值为 msys64 目录路径（例如 C:\msys64）。Visual Studio 版本现在由工具链自动检测，无需手动指定版本号。
::: warning 从 v2 迁移
v2 依赖 php-sdk-binary-tools，并在每次构建时需要传入 --with-sdk-binary-dir 和 --vs-ver 参数。在 v3 中这些选项已被移除。请从所有 CI 脚本中删除这些参数，并使用 spc doctor --install 一次性完成 Windows 构建环境的配置。
:::
已重命名 / 已弃用的选项
以下选项已重命名。部分旧名称仍作为弃用别名被接受，但建议尽快更新脚本。
| v2 选项 | v3 选项 | 状态 |
|---|---|---|
--prefer-pre-built |
--prefer-binary / -p |
旧名称保留为弃用别名 |
--with-libs=<list> |
--with-packages=<list> |
— |
--with-suggested-libs / -L |
--with-suggests |
旧 -L / -E 已移除 |
--with-suggested-exts / -E |
--with-suggests |
已合并为单一标志 |
示例
# v2
spc build curl,gd --build-cli --with-libs="openssl" -L -E
# v3
spc build curl,gd --build-cli --with-packages="openssl" --with-suggests
build 命令行为变化
build 命令（别名：build:php）仍然可用。但 v3 新增了专用的单目标构建命令，无需再传入 SAPI 选择标志：
| v2 | v3 等价命令 |
|---|---|
spc build exts --build-cli |
spc build:php-cli exts |
spc build exts --build-fpm |
spc build:php-fpm exts |
spc build exts --build-cgi |
spc build:php-cgi exts |
spc build exts --build-micro |
spc build:php-micro exts |
spc build exts --build-embed |
spc build:php-embed exts |
spc build exts --build-frankenphp |
spc build:frankenphp exts |
如果需要在一次构建中同时编译多个 SAPI，请继续使用 build:php（--build-* 标志在该命令下仍然有效）。
构建命令自动下载依赖
v3 中，所有 build:* 命令在构建前会自动下载缺失的依赖包，不再需要单独执行 spc download：
# v2 — 需要两步
spc download --for-extensions=curl,gd
spc build curl,gd --build-cli
# v3 — 一步即可
spc build:php-cli curl,gd
如需跳过自动下载（例如在 CI 中源码已预先缓存），可传入 --no-download：
spc build:php-cli curl,gd --no-download
download 命令选项变化
| v2 | v3 | 说明 |
|---|---|---|
--prefer-pre-built |
--prefer-binary / -p |
弃用别名保留 |
--with-libs |
--for-libs |
与包过滤分开 |
| （无等价） | --for-packages |
统一包过滤器 |
| （无等价） | --parallel / -P |
并行下载 |
| （无等价） | --retry / -R |
失败重试 |
已移除的 dev 命令
以下开发辅助命令已被移除或合并：
| v2 命令 | v3 替代方案 |
|---|---|
dev:extensions / list-ext |
spc dev:info <package> |
dev:ext-version / dev:ext-ver |
spc dev:info <package> |
dev:lib-version / dev:lib-ver |
spc dev:info <package> |
dev:php-version / dev:php-ver |
spc dev:info php-src |
dev:gen-ext-dep-docs + dev:gen-lib-dep-docs |
spc dev:gen-deps-data |
已重命名的 dev 命令
| v2 | v3 | 说明 |
|---|---|---|
dev:sort-config / sort-config |
dev:lint-config |
旧别名仍可用 |
v3 新增命令
以下命令为 v3 新增，v2 中没有对应命令：
| 命令 | 说明 |
|---|---|
spc reset |
清理 buildroot/ 和 source/ 目录 |
spc check-update |
检查 artifact 的最新版本 |
spc build:php-cli |
构建 CLI SAPI（无需标志） |
spc build:php-fpm |
构建 PHP-FPM（无需标志） |
spc build:php-cgi |
构建 PHP CGI（无需标志） |
spc build:php-micro |
构建 phpmicro（无需标志） |
spc build:php-embed |
构建 embed SAPI（无需标志） |
spc build:frankenphp |
构建 FrankenPHP（无需标志） |
spc dev:shell |
进入带构建环境的交互式 shell |
spc dev:is-installed |
检查某个包是否已正确安装 |
spc dev:dump-stages |
将所有包的构建阶段导出为 JSON |
spc dev:dump-capabilities |
导出包的可构建/可安装能力 |
spc dev:info |
显示某个包的配置信息 |
craft.yml 变化
已移除：build-options.with-added-patch
build-options 下的 with-added-patch 键不再被解析，将被静默忽略。请从你的 craft.yml 中移除它：
# v2 — 请删除此块
build-options:
with-added-patch:
- my-patch.php
libs → packages（两者均可用）
顶层 libs 字段仍然有效。v3 中推荐使用 packages，它是 libs 的超集，还涵盖其他工具类包：
# v2
libs: nghttp2,liblz4
# v3（推荐）
packages: nghttp2,liblz4
env.ini 变量重命名
如果你在 config/env.ini 中进行了自定义，或在 CI 中导出了环境变量，请更新以下变量名：
| v2 变量名 | v3 变量名 |
|---|---|
SPC_LINUX_DEFAULT_CC |
SPC_DEFAULT_CC |
SPC_LINUX_DEFAULT_CXX |
SPC_DEFAULT_CXX |
SPC_LINUX_DEFAULT_AR |
SPC_DEFAULT_AR |
SPC_LINUX_DEFAULT_LD |
SPC_DEFAULT_LD |
SPC_LIBC |
SPC_TARGET |
SPC_TARGET 使用新的格式，将架构与 libc 编码在一个字符串中，例如：
| v2 | v3 |
|---|---|
SPC_LIBC=musl |
SPC_TARGET=x86_64-linux-musl |
SPC_LIBC=gnu |
SPC_TARGET=x86_64-linux-gnu.2.17 |
v3 还新增了若干日志相关变量（SPC_ENABLE_LOG_FILE、SPC_LOGS_DIR、SPC_PRESERVE_LOGS）。详情参见环境变量。