static-php-cli/assets/zh_guide_sapi-reference.md.DXv5eV6I.js

import{_ as s,c as a,o as e,aj as l}from"./chunks/framework.C2AwuPrQ.js";const o=JSON.parse('{"title":"PHP SAPI 构建参考","description":"","frontmatter":{"outline":"deep"},"headers":[],"relativePath":"zh/guide/sapi-reference.md","filePath":"zh/guide/sapi-reference.md"}'),n={name:"zh/guide/sapi-reference.md"};function h(p,i,t,d,k,r){return e(),a("div",null,[...i[0]||(i[0]=[l(`<h1 id="php-sapi-构建参考" tabindex="-1">PHP SAPI 构建参考 <a class="header-anchor" href="#php-sapi-构建参考" aria-label="Permalink to “PHP SAPI 构建参考”">​</a></h1><div class="tip custom-block"><p class="custom-block-title custom-block-title-default">TIP</p><p>如果你采用的是 spc 二进制方式安装，请将本章节中的所有 <code>spc</code> 替换为 <code>./spc</code> 或 <code>.\\spc.exe</code>。</p><p>如果你采用的是源码安装，请将 <code>spc</code> 替换为 <code>bin/spc</code>。</p></div><p>本页详细介绍 StaticPHP 支持的各类 PHP SAPI 的构建参数和使用方式。</p><h2 id="概览" tabindex="-1">概览 <a class="header-anchor" href="#概览" aria-label="Permalink to “概览”">​</a></h2><table tabindex="0"><thead><tr><th>SAPI</th><th>构建参数</th><th>产物路径（Linux/macOS）</th><th>产物路径（Windows）</th><th>平台支持</th></tr></thead><tbody><tr><td>cli</td><td><code>--build-cli</code></td><td><code>buildroot/bin/php</code></td><td><code>buildroot/bin/php.exe</code></td><td>Linux、macOS、Windows</td></tr><tr><td>fpm</td><td><code>--build-fpm</code></td><td><code>buildroot/bin/php-fpm</code></td><td>—</td><td>Linux、macOS</td></tr><tr><td>micro</td><td><code>--build-micro</code></td><td><code>buildroot/bin/micro.sfx</code></td><td><code>buildroot/bin/micro.sfx</code></td><td>Linux、macOS、Windows</td></tr><tr><td>embed</td><td><code>--build-embed</code></td><td><code>buildroot/lib/libphp.a</code></td><td><code>buildroot/lib/php8embed.lib</code></td><td>Linux、macOS、Windows</td></tr><tr><td>frankenphp</td><td><code>--build-frankenphp</code></td><td><code>buildroot/bin/frankenphp</code></td><td><code>buildroot/bin/frankenphp.exe</code></td><td>Linux、macOS、Windows</td></tr></tbody></table><h2 id="cli" tabindex="-1">cli <a class="header-anchor" href="#cli" aria-label="Permalink to “cli”">​</a></h2><p><code>cli</code> 是标准的 PHP 命令行程序，适用于在终端执行 PHP 脚本、交互式 shell 等场景。</p><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 style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl,curl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span></span></code></pre></div><p>Windows 下产物为 <code>buildroot/bin/php.exe</code>，其他平台为 <code>buildroot/bin/php</code>。</p><p>完整选项参见 <a href="./cli-reference.html#sapi-selection">build:php — SAPI 选择</a> 和 <a href="./cli-reference.html#common-build-options">build:php — 通用构建选项</a>。</p><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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 查看版本和已加载扩展</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -v</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -m</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 执行脚本</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-script.php</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 交互模式</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -a</span></span></code></pre></div><h3 id="php-ini-路径" tabindex="-1">php.ini 路径 <a class="header-anchor" href="#php-ini-路径" aria-label="Permalink to “php.ini 路径”">​</a></h3><p>静态编译的 PHP cli 按以下顺序搜索 <code>php.ini</code>：</p><ol><li>命令行参数 <code>-c /path/to/php.ini</code> 指定的路径</li><li><code>PHP_INI_PATH</code> 环境变量指定的路径</li><li>编译时通过 <code>--with-config-file-path</code> 指定的目录（默认为 <code>/usr/local/etc/php</code>）</li></ol><p>可以通过 <code>./buildroot/bin/php --ini</code> 查看 PHP 实际使用的 ini 路径。</p><h3 id="硬编码-ini" tabindex="-1">硬编码 INI <a class="header-anchor" href="#硬编码-ini" aria-label="Permalink to “硬编码 INI”">​</a></h3><p>使用 <code>-I</code> 参数可以在编译时将 INI 配置硬编码到二进制中，无需额外的 <code>php.ini</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</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,pcntl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;memory_limit=4G&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;disable_functions=system,exec&quot;</span></span></code></pre></div><p>硬编码 INI 适用于 <code>cli</code>、<code>micro</code>、<code>embed</code> SAPI。</p><h2 id="fpm" tabindex="-1">fpm <a class="header-anchor" href="#fpm" aria-label="Permalink to “fpm”">​</a></h2><p><code>fpm</code>（FastCGI Process Manager）与 Nginx、Apache 等 Web 服务器配合使用，适用于传统的 Web 应用部署场景。</p><div class="warning custom-block"><p class="custom-block-title custom-block-title-default">WARNING</p><p><code>fpm</code> 不支持 Windows 平台。</p></div><h3 id="构建-1" tabindex="-1">构建 <a class="header-anchor" href="#构建-1" 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 style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl,curl,pdo_mysql&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-fpm</span></span></code></pre></div><p>产物为 <code>buildroot/bin/php-fpm</code>。</p><p>完整选项参见 <a href="./cli-reference.html#sapi-selection">build:php — SAPI 选择</a> 和 <a href="./cli-reference.html#common-build-options">build:php — 通用构建选项</a>。</p><h3 id="使用-1" tabindex="-1">使用 <a class="header-anchor" href="#使用-1" aria-label="Permalink to “使用”">​</a></h3><p>将 <code>buildroot/bin/php-fpm</code> 拷贝到服务器，像普通的 <code>php-fpm</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;"># 查看版本</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php-fpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -v</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 指定配置文件启动</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php-fpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -c</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/php.ini</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -y</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/php-fpm.conf</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 测试配置文件</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/php-fpm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -t</span></span></code></pre></div><h3 id="与-nginx-配合使用示例" tabindex="-1">与 Nginx 配合使用示例 <a class="header-anchor" href="#与-nginx-配合使用示例" aria-label="Permalink to “与 Nginx 配合使用示例”">​</a></h3><div class="language-nginx"><button title="Copy Code" class="copy"></button><span class="lang">nginx</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:#D73A49;--shiki-dark:#F97583;">server</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    listen </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">80</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    root </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">/var/www/html;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    index </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">index.php;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    location</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ~</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;"> \\.php$ </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        fastcgi_pass </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">127.0.0.1:9000;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        fastcgi_param </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">SCRIPT_FILENAME $document_root$fastcgi_script_name;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        include </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">fastcgi_params;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p><code>php-fpm.conf</code> 示例：</p><div class="language-ini"><button title="Copy Code" class="copy"></button><span class="lang">ini</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;">[global]</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pid</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = /var/run/php-fpm.pid</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">error_log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = /var/log/php-fpm.log</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">[www]</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">listen</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 127.0.0.1:9000</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = dynamic</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.max_children</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 5</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.start_servers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 2</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.min_spare_servers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 1</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">pm.max_spare_servers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = 3</span></span></code></pre></div><h2 id="micro" tabindex="-1">micro <a class="header-anchor" href="#micro" aria-label="Permalink to “micro”">​</a></h2><p><code>micro</code> 是基于 <a href="https://github.com/easysoft/phpmicro" target="_blank" rel="noreferrer">phpmicro</a> 的自包含可执行文件 SAPI。通过 <code>spc micro:combine</code> 命令，可以将 <code>micro.sfx</code> 与 PHP 代码合并为一个独立的可执行文件，无需在目标机器上安装 PHP。</p><h3 id="构建-2" tabindex="-1">构建 <a class="header-anchor" href="#构建-2" 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 style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,phar,openssl,curl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-micro</span></span></code></pre></div><p>产物为 <code>buildroot/bin/micro.sfx</code>。</p><p>完整选项参见 <a href="./cli-reference.html#sapi-selection">build:php — SAPI 选择</a>、<a href="./cli-reference.html#common-build-options">build:php — 通用构建选项</a> 和 <a href="./cli-reference.html#micro-options">build:php — micro 专用选项</a>。</p><h3 id="打包应用" tabindex="-1">打包应用 <a class="header-anchor" href="#打包应用" aria-label="Permalink to “打包应用”">​</a></h3><p>使用 <code>micro:combine</code> 命令将 PHP 脚本或 phar 文件打包：</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;"># 打包 PHP 脚本</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">echo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&lt;?php echo &#39;Hello, World!&#39; . PHP_EOL;&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> hello.php</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> hello.php</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=hello</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./hello</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 打包 phar 文件</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./your-app</span></span></code></pre></div><h3 id="注入-ini-配置" tabindex="-1">注入 INI 配置 <a class="header-anchor" href="#注入-ini-配置" aria-label="Permalink to “注入 INI 配置”">​</a></h3><p>打包时可以通过命令行参数或 ini 文件注入运行时配置：</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;"># 通过命令行参数注入（-I 是 --with-ini-set 的简写）</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;memory_limit=512M&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -I</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;curl.cainfo=/etc/ssl/certs/ca-certificates.crt&quot;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 通过 ini 文件注入（-N 是 --with-ini-file 的简写）</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/custom.ini</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title custom-block-title-default">TIP</p><p><code>-I</code> 注入的 INI 是运行时配置，通过在 <code>micro.sfx</code> 末尾追加特殊结构实现。这与编译时用 <code>-I</code> 硬编码 INI 不同，两者可以共存。</p></div><h3 id="伪装为-cli-sapi" tabindex="-1">伪装为 cli SAPI <a class="header-anchor" href="#伪装为-cli-sapi" aria-label="Permalink to “伪装为 cli SAPI”">​</a></h3><p>部分框架会检查 <code>PHP_SAPI</code> 的值，并限制在非 <code>cli</code> 环境下运行。<code>micro</code> 的 <code>PHP_SAPI</code> 默认值为 <code>micro</code>，可通过编译参数让其伪装为 <code>cli</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</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,phar&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-micro</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-micro-fake-cli</span></span></code></pre></div><h3 id="指定自定义-micro-sfx-路径" tabindex="-1">指定自定义 micro.sfx 路径 <a class="header-anchor" href="#指定自定义-micro-sfx-路径" aria-label="Permalink to “指定自定义 micro.sfx 路径”">​</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 style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> micro:combine</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> your-app.phar</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --output=your-app</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --with-micro=/path/to/your/micro.sfx</span></span></code></pre></div><h3 id="关于-phar-的路径问题" tabindex="-1">关于 phar 的路径问题 <a class="header-anchor" href="#关于-phar-的路径问题" aria-label="Permalink to “关于 phar 的路径问题”">​</a></h3><p>将应用打包为 phar 后，phar 内部使用相对路径可能与预期不符。请参考<a href="./../develop/structure.html">开发者文档 - Phar 目录问题</a>了解详情。</p><h2 id="embed" tabindex="-1">embed <a class="header-anchor" href="#embed" aria-label="Permalink to “embed”">​</a></h2><p><code>embed</code> SAPI 将 PHP 编译为静态库（Linux/macOS 下为 <code>libphp.a</code>，Windows 下为 <code>php8embed.lib</code>），可嵌入到其他 C/C++ 程序中运行 PHP 代码。</p><h3 id="构建-3" tabindex="-1">构建 <a class="header-anchor" href="#构建-3" 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 style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-embed</span></span></code></pre></div><p>产物：</p><ul><li>Linux/macOS：<code>buildroot/lib/libphp.a</code>，头文件在 <code>buildroot/include/</code></li><li>Windows：<code>buildroot/lib/php8embed.lib</code>，头文件在 <code>buildroot/include/</code></li></ul><p>完整选项参见 <a href="./cli-reference.html#sapi-selection">build:php — SAPI 选择</a>、<a href="./cli-reference.html#common-build-options">build:php — 通用构建选项</a> 和 <a href="./cli-reference.html#embed-options">build:php — embed 专用选项</a>。</p><div class="tip custom-block"><p class="custom-block-title custom-block-title-default">TIP</p><p>如何将 <code>libphp.a</code> / <code>php8embed.lib</code> 链接到你自己的项目（包括编译器选择、<code>dev:shell</code> 使用方式和完整 C 示例），将在开发者文档中专门介绍。</p></div><h2 id="frankenphp" tabindex="-1">frankenphp <a class="header-anchor" href="#frankenphp" aria-label="Permalink to “frankenphp”">​</a></h2><p><code>frankenphp</code> 是基于 <a href="https://github.com/php/frankenphp" target="_blank" rel="noreferrer">FrankenPHP</a> 的现代 PHP 应用服务器，内置 Caddy，支持 HTTP/2、HTTP/3、自动 HTTPS 等特性。</p><div class="tip custom-block"><p class="custom-block-title custom-block-title-default">TIP</p><p>StaticPHP 构建出的 <code>frankenphp</code> 是单个完全自包含的可执行文件。这与 FrankenPHP 官方提供的发行版不同，官方版本为动态链接二进制，需要单独安装 PHP。</p></div><div class="warning custom-block"><p class="custom-block-title custom-block-title-default">WARNING</p><p>FrankenPHP 必须启用线程安全模式，构建时务必加上 <code>--enable-zts</code>。</p></div><h3 id="构建-4" tabindex="-1">构建 <a class="header-anchor" href="#构建-4" 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 style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl,curl,pdo_mysql&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-frankenphp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --enable-zts</span></span></code></pre></div><p>Linux/macOS 下产物为 <code>buildroot/bin/frankenphp</code>，Windows 下为 <code>buildroot/bin/frankenphp.exe</code>。</p><p>完整选项参见 <a href="./cli-reference.html#sapi-selection">build:php — SAPI 选择</a>、<a href="./cli-reference.html#common-build-options">build:php — 通用构建选项</a> 和 <a href="./cli-reference.html#frankenphp-options">build:php — frankenphp 专用选项</a>。</p><h3 id="使用-2" tabindex="-1">使用 <a class="header-anchor" href="#使用-2" 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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 查看版本</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/frankenphp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> version</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 以 PHP 内置服务器模式运行（用于开发调试）</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/frankenphp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> php-server</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 运行 Worker 模式</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">./buildroot/bin/frankenphp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /path/to/Caddyfile</span></span></code></pre></div><p>更多用法请参考 <a href="https://frankenphp.dev/docs/" target="_blank" rel="noreferrer">FrankenPHP 官方文档</a>。</p><h2 id="动态扩展加载" tabindex="-1">动态扩展加载 <a class="header-anchor" href="#动态扩展加载" aria-label="Permalink to “动态扩展加载”">​</a></h2><p>静态 PHP 二进制是否能够通过 <code>dl()</code> 在运行时加载扩展，取决于其链接方式。</p><p><strong>macOS</strong> — 构建产物始终动态链接系统库，支持通过 <code>dl()</code> 或 <code>php.ini</code> 在运行时加载 <code>.so</code> 扩展。</p><p><strong>Linux</strong> — StaticPHP 默认构建目标为 <code>native-native-musl</code>：完全静态链接 musl libc 的二进制。由于运行时不存在动态链接器，<code>dl()</code> 被禁用，FFI 扩展无法使用，也无法加载任何外部 <code>.so</code> 扩展。</p><p>如需在 Linux 上支持动态扩展加载，请在构建前设置 <code>SPC_TARGET</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:#24292E;--shiki-dark:#E1E4E8;">SPC_TARGET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">native-native-gnu.2.17</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> spc</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build:php</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bcmath,openssl&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-cli</span></span></code></pre></div><p>如果你采用的是源码安装，也可以在 <code>config/env.ini</code> 中设置 <code>SPC_TARGET=native-native-gnu.2.17</code>，将其作为所有构建的默认值。</p><p>这将使用 Zig 工具链构建出一个准静态二进制，动态链接 glibc 2.17，可运行于大多数现代 GNU/Linux 发行版，无需 Docker，也无需额外的交叉编译工具链。该产物支持 <code>dl()</code>、FFI 和运行时加载 <code>.so</code> 扩展，但无法运行于 Alpine Linux 等基于 musl 的系统。</p><p><strong>Windows</strong> — Windows 上的 PHP 扩展均以 <code>.dll</code> 形式分发，且依赖官方动态构建的 PHP 中附带的 DLL 文件。StaticPHP 构建的静态 PHP 可执行文件不包含这些 DLL，因此 Windows 不支持动态扩展加载，所有扩展必须在构建时静态编译进去。</p>`,83)])])}const b=s(n,[["render",h]]);export{o as __pageData,b as default};