assets/zh_guide_migrate-from-v2.md.Df8wnmfP.js

import{_ as d,c as e,o as i,aj as s}from"./chunks/framework.C2AwuPrQ.js";const k=JSON.parse('{"title":"从 v2 迁移","description":"","frontmatter":{},"headers":[],"relativePath":"zh/guide/migrate-from-v2.md","filePath":"zh/guide/migrate-from-v2.md"}'),a={name:"zh/guide/migrate-from-v2.md"};function l(c,t,h,o,n,p){return i(),e("div",null,[...t[0]||(t[0]=[s(`<h1 id="从-v2-迁移" tabindex="-1">从 v2 迁移 <a class="header-anchor" href="#从-v2-迁移" aria-label="Permalink to “从 v2 迁移”"></a></h1><p>StaticPHP v3 是一次完整的重写。核心构建流程（<code>download → build → combine</code>）保持不变，但部分命令、选项和配置字段已发生变化。本页列出了切换前所有需要更新的内容。</p><div class="info custom-block"><p class="custom-block-title">范围说明</p><p>本指南仅涵盖面向用户的 CLI 命令、选项、<code>craft.yml</code> 字段和 <code>env.ini</code> 变量名称。不涵盖内部 PHP API。</p></div><h2 id="文档地址变更" tabindex="-1">文档地址变更 <a class="header-anchor" href="#文档地址变更" aria-label="Permalink to “文档地址变更”"></a></h2><p>官方文档站点已迁移：</p><ul><li><strong>v3 文档（当前）</strong>：<a href="https://static-php.dev" target="_blank" rel="noreferrer">https://static-php.dev</a> — 主站现在托管 v3 文档。</li><li><strong>v2 文档（归档）</strong>：<a href="https://static-php.github.io/v2-docs/" target="_blank" rel="noreferrer">https://static-php.github.io/v2-docs/</a> — v2 文档已归档保留，供参考。</li></ul><p>请更新你保存的书签或内部链接。</p><h2 id="spc-二进制下载地址变更" tabindex="-1"><code>spc</code> 二进制下载地址变更 <a class="header-anchor" href="#spc-二进制下载地址变更" aria-label="Permalink to “spc 二进制下载地址变更”"></a></h2><p>nightly <code>spc</code> 自包含二进制文件已迁移到新路径：</p><table tabindex="0"><thead><tr><th></th><th>地址</th></tr></thead><tbody><tr><td><strong>v2</strong></td><td><code>https://dl.static-php.dev/static-php-cli/spc-bin/nightly/</code></td></tr><tr><td><strong>v3</strong></td><td><code>https://dl.static-php.dev/v3/spc-bin/nightly/</code></td></tr></tbody></table><p>请更新所有直接下载 <code>spc</code> 二进制的 CI 脚本或初始化命令，例如：</p><div class="language-bash"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v2</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -o</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v3</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -o</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://dl.static-php.dev/v3/spc-bin/nightly/spc-linux-x86_64</span></span></code></pre></div><h2 id="已移除的命令" tabindex="-1">已移除的命令 <a class="header-anchor" href="#已移除的命令" aria-label="Permalink to “已移除的命令”"></a></h2><table tabindex="0"><thead><tr><th>v2 命令</th><th>v3 替代方案</th><th>说明</th></tr></thead><tbody><tr><td><code>del-download</code></td><td><code>spc reset</code></td><td><code>reset</code> 支持 <code>--with-pkgroot</code> 和 <code>--with-download</code> 以进行更细粒度的控制</td></tr><tr><td><code>del-download --all</code></td><td><code>spc reset --with-download</code></td><td>删除下载缓存目录</td></tr></tbody></table><h2 id="已移除的选项" tabindex="-1">已移除的选项 <a class="header-anchor" href="#已移除的选项" aria-label="Permalink to “已移除的选项”"></a></h2><h3 id="with-added-patch-p-build-命令" tabindex="-1"><code>--with-added-patch</code> / <code>-P</code>（build 命令） <a class="header-anchor" href="#with-added-patch-p-build-命令" aria-label="Permalink to “--with-added-patch / -P（build 命令）”"></a></h3><p>该选项允许在特定构建阶段注入外部 PHP patch 脚本。<strong>v3 已完全移除此功能。</strong></p><p>目前没有直接的替代方案。如果你依赖此功能，请考虑以下方式：</p><ul><li>将你的 patch 贡献到 StaticPHP 的上游仓库。</li><li>对于项目专用的 patch，可以使用自定义 registry 并编写 Package 类。详情参见<a href="/zh/develop/extending/package-classes.html">编写 Package 类</a>。</li></ul><div class="tip custom-block"><p class="custom-block-title">未来计划</p><p>未来版本可能会提供用于轻量级 patch 的单文件 hook API。</p></div><h3 id="windows-专有-with-sdk-binary-dir-和-vs-ver" tabindex="-1">Windows 专有：<code>--with-sdk-binary-dir</code> 和 <code>--vs-ver</code> <a class="header-anchor" href="#windows-专有-with-sdk-binary-dir-和-vs-ver" aria-label="Permalink to “Windows 专有：--with-sdk-binary-dir 和 --vs-ver”"></a></h3><p>这两个选项已不再被命令行接受。请改为设置 <code>PHP_SDK_PATH</code> 环境变量，指向你的 PHP SDK binary tools 目录。Visual Studio 版本现在由工具链配置统一管理。</p><h2 id="已重命名-已弃用的选项" tabindex="-1">已重命名 / 已弃用的选项 <a class="header-anchor" href="#已重命名-已弃用的选项" aria-label="Permalink to “已重命名 / 已弃用的选项”"></a></h2><p>以下选项已重命名。部分旧名称仍作为弃用别名被接受，但建议尽快更新脚本。</p><table tabindex="0"><thead><tr><th>v2 选项</th><th>v3 选项</th><th>状态</th></tr></thead><tbody><tr><td><code>--prefer-pre-built</code></td><td><code>--prefer-binary</code> / <code>-p</code></td><td>旧名称保留为弃用别名</td></tr><tr><td><code>--with-libs=&lt;list&gt;</code></td><td><code>--with-packages=&lt;list&gt;</code></td><td>—</td></tr><tr><td><code>--with-suggested-libs</code> / <code>-L</code></td><td><code>--with-suggests</code></td><td>旧 <code>-L</code> / <code>-E</code> 已移除</td></tr><tr><td><code>--with-suggested-exts</code> / <code>-E</code></td><td><code>--with-suggests</code></td><td>已合并为单一标志</td></tr></tbody></table><h3 id="示例" tabindex="-1">示例 <a class="header-anchor" href="#示例" aria-label="Permalink to “示例”"></a></h3><div class="language-bash"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span styl
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-libs=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;openssl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -L</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -E</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v3</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-packages=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;openssl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-suggests</span></span></code></pre></div><h2 id="build-命令行为变化" tabindex="-1"><code>build</code> 命令行为变化 <a class="header-anchor" href="#build-命令行为变化" aria-label="Permalink to “build 命令行为变化”"></a></h2><p><code>build</code> 命令（别名：<code>build:php</code>）仍然可用。但 v3 新增了<strong>专用的单目标构建命令</strong>，无需再传入 SAPI 选择标志：</p><table tabindex="0"><thead><tr><th>v2</th><th>v3 等价命令</th></tr></thead><tbody><tr><td><code>spc build exts --build-cli</code></td><td><code>spc build:php-cli exts</code></td></tr><tr><td><code>spc build exts --build-fpm</code></td><td><code>spc build:php-fpm exts</code></td></tr><tr><td><code>spc build exts --build-cgi</code></td><td><code>spc build:php-cgi exts</code></td></tr><tr><td><code>spc build exts --build-micro</code></td><td><code>spc build:php-micro exts</code></td></tr><tr><td><code>spc build exts --build-embed</code></td><td><code>spc build:php-embed exts</code></td></tr><tr><td><code>spc build exts --build-frankenphp</code></td><td><code>spc build:frankenphp exts</code></td></tr></tbody></table><p>如果需要在一次构建中同时编译多个 SAPI，请继续使用 <code>build:php</code>（<code>--build-*</code> 标志在该命令下仍然有效）。</p><h3 id="构建命令自动下载依赖" tabindex="-1">构建命令自动下载依赖 <a class="header-anchor" href="#构建命令自动下载依赖" aria-label="Permalink to “构建命令自动下载依赖”"></a></h3><p>v3 中，所有 <code>build:*</code> 命令在构建前会自动下载缺失的依赖包，不再需要单独执行 <code>spc download</code>：</p><div class="language-bash"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v2 — 需要两步</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> download</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --for-extensions=curl,gd</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v3 — 一步即可</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php-cli</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span></span></code></pre></div><p>如需跳过自动下载（例如在 CI 中源码已预先缓存），可传入 <code>--no-download</code>：</p><div class="language-bash"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php-cli</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> curl,gd</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-download</span></span></code></pre></div><h2 id="download-命令选项变化" tabindex="-1"><code>download</code> 命令选项变化 <a class="header-anchor" href="#download-命令选项变化" aria-label="Permalink to “download 命令选项变化”"></a></h2><table tabindex="0"><thead><tr><th>v2</th><th>v3</th><th>说明</th></tr></thead><tbody><tr><td><code>--prefer-pre-built</code></td><td><code>--prefer-binary</code> / <code>-p</code></td><td>弃用别名保留</td></tr><tr><td><code>--with-libs</code></td><td><code>--for-libs</code></td><td>与包过滤分开</td></tr><tr><td><em>（无等价）</em></td><td><code>--for-packages</code></td><td>统一包过滤器</td></tr><tr><td><em>（无等价）</em></td><td><code>--parallel</code> / <code>-P</code></td><td>并行下载</td></tr><tr><td><em>（无等价）</em></td><td><code>--retry</code> / <code>-R</code></td><td>失败重试</td></tr></tbody></table><h2 id="已移除的-dev-命令" tabindex="-1">已移除的 dev 命令 <a class="header-anchor" href="#已移除的-dev-命令" aria-label="Permalink to “已移除的 dev 命令”"></a></h2><p>以下开发辅助命令已被移除或合并：</p><table tabindex="0"><thead><tr><th>v2 命令</th><th>v3 替代方案</th></tr></thead><tbody><tr><td><code>dev:extensions</code> / <code>list-ext</code></td><td><code>spc dev:info &lt;package&gt;</code></td></tr><tr><td><code>dev:ext-version</code> / <code>dev:ext-ver</code></td><td><code>spc dev:info &lt;package&gt;</code></td></tr><tr><td><code>dev:lib-version</code> / <code>dev:lib-ver</code></td><td><code>spc dev:info &lt;package&gt;</code></td></tr><tr><td><code>dev:php-version</code> / <code>dev:php-ver</code></td><td><code>spc dev:info php-src</code></td></tr><tr><td><code>dev:gen-ext-dep-docs</code> + <code>dev:gen-lib-dep-docs</code></td><td><code>spc dev:gen-deps-data</code></td></tr></tbody></table><h2 id="已重命名的-dev-命令" tabindex="-1">已重命名的 dev 命令 <a class="header-anchor" href="#已重命名的-dev-命令" aria-label="Permalink to “已重命名的 dev 命令”"></a></h2><table tabindex="0"><thead><tr><th>v2</th><th>v3</th><th>说明</th></tr></thead><tbody><tr><td><code>dev:sort-config</code> / <code>sort-config</code></td><td><code>dev:lint-config</code></td><td>旧别名仍可用</td></tr></tbody></table><h2 id="v3-新增命令" tabindex="-1">v3 新增命令 <a class="header-anchor" href="#v3-新增命令" aria-label="Permalink to “v3 新增命令”"></a></h2><p>以下命令为 v3 新增，v2 中没有对应命令：</p><table tabindex="0"><thead><tr><th>命令</th><th>说明</th></tr></thead><tbody><tr><td><code>spc reset</code></td><td>清理 <code>buildroot/</code> 和 <code>source/</code> 目录</td></tr><tr><td><code>spc check-update</code></td><td>检查 artifact 的最新版本</td></tr><tr><td><code>spc build:php-cli</code></td><td>构建 CLI SAPI（无需标志）</td></tr><tr><td><code>spc build:php-fpm</code></td><td>构建 PHP-FPM（无需标志）</td></tr><tr><td><code>spc build:php-cgi</code></td><td>构建 PHP CGI（无需标志）</td></tr>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">build-options</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  with-added-patch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">my-patch.php</span></span></code></pre></div><h3 id="libs-→-packages-两者均可用" tabindex="-1"><code>libs</code> → <code>packages</code>（两者均可用） <a class="header-anchor" href="#libs-→-packages-两者均可用" aria-label="Permalink to “libs → packages（两者均可用）”"></a></h3><p>顶层 <code>libs</code> 字段仍然有效。v3 中推荐使用 <code>packages</code>，它是 <code>libs</code> 的超集，还涵盖其他工具类包：</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v2</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">libs</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nghttp2,liblz4</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># v3（推荐）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">packages</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nghttp2,liblz4</span></span></code></pre></div><h2 id="env-ini-变量重命名" tabindex="-1"><code>env.ini</code> 变量重命名 <a class="header-anchor" href="#env-ini-变量重命名" aria-label="Permalink to “env.ini 变量重命名”"></a></h2><p>如果你在 <code>config/env.ini</code> 中进行了自定义，或在 CI 中导出了环境变量，请更新以下变量名：</p><table tabindex="0"><thead><tr><th>v2 变量名</th><th>v3 变量名</th></tr></thead><tbody><tr><td><code>SPC_LINUX_DEFAULT_CC</code></td><td><code>SPC_DEFAULT_CC</code></td></tr><tr><td><code>SPC_LINUX_DEFAULT_CXX</code></td><td><code>SPC_DEFAULT_CXX</code></td></tr><tr><td><code>SPC_LINUX_DEFAULT_AR</code></td><td><code>SPC_DEFAULT_AR</code></td></tr><tr><td><code>SPC_LINUX_DEFAULT_LD</code></td><td><code>SPC_DEFAULT_LD</code></td></tr><tr><td><code>SPC_LIBC</code></td><td><code>SPC_TARGET</code></td></tr></tbody></table><p><code>SPC_TARGET</code> 使用新的格式，将架构与 libc 编码在一个字符串中，例如：</p><table tabindex="0"><thead><tr><th>v2</th><th>v3</th></tr></thead><tbody><tr><td><code>SPC_LIBC=musl</code></td><td><code>SPC_TARGET=x86_64-linux-musl</code></td></tr><tr><td><code>SPC_LIBC=gnu</code></td><td><code>SPC_TARGET=x86_64-linux-gnu.2.17</code></td></tr></tbody></table><p>v3 还新增了若干日志相关变量（<code>SPC_ENABLE_LOG_FILE</code>、<code>SPC_LOGS_DIR</code>、<code>SPC_PRESERVE_LOGS</code>）。详情参见<a href="/zh/guide/env-vars.html">环境变量</a>。</p>`,59)])])}const b=d(a,[["render",l]]);export{k as __pageData,b as default};