Files
static-php-cli/zh/guide/sapi-reference.html

78 lines
57 KiB
HTML
Raw Normal View History

<!DOCTYPE html>
<html lang="zh" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>PHP SAPI 构建参考 | StaticPHP</title>
<meta name="description" content="A powerful tool designed for building portable executables including PHP, extensions, and more.">
<meta name="generator" content="VitePress v2.0.0-alpha.18">
<link rel="preload stylesheet" href="/assets/style.C4OPn_QV.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.Bw02Lh2k.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Cy4MYw_J.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.C_odZu9O.js">
<link rel="modulepreload" href="/assets/chunks/framework.DrNIf5Lg.js">
<link rel="modulepreload" href="/assets/zh_guide_sapi-reference.md.TjYI_FdR.lean.js">
<script id="check-dark-mode">(()=>{let e=localStorage.getItem(`vitepress-theme-appearance`)||`auto`,t=window.matchMedia(`(prefers-color-scheme: dark)`).matches;(!e||e===`auto`?t:e===`dark`)&&document.documentElement.classList.add(`dark`)})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle(`mac`,/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-0cf61682><!--[--><!--]--><!--[--><span tabindex="-1" data-v-414181b2></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-414181b2>Skip to content</a><!--]--><!----><header class="VPNav" data-v-0cf61682 data-v-9f75dce3><div class="VPNavBar has-sidebar top" data-v-9f75dce3 data-v-9ca1369d><div class="wrapper" data-v-9ca1369d><div class="container" data-v-9ca1369d><div class="title" data-v-9ca1369d><div class="VPNavBarTitle has-sidebar" data-v-9ca1369d data-v-1e38c6bc><a class="title" href="/zh/" data-v-1e38c6bc><!--[--><!--]--><!--[--><img class="VPImage logo" src="/images/static-php_nobg.png" alt data-v-8426fc1a><!--]--><span data-v-1e38c6bc>StaticPHP</span><!--[--><!--]--></a></div></div><div class="content" data-v-9ca1369d><div class="content-body" data-v-9ca1369d><!--[--><!--]--><div class="VPNavBarSearch search" data-v-9ca1369d data-v-2fc7f2c6><!--[--><button type="button" class="VPNavBarSearchButton" aria-label="Search" aria-keyshortcuts="/ control+k meta+k" data-v-2fc7f2c6 data-v-baa3be99><span class="vpi-search" aria-hidden="true" data-v-baa3be99></span><span class="text" data-v-baa3be99>Search</span><span class="keys" aria-hidden="true" data-v-baa3be99><kbd class="key-cmd" data-v-baa3be99></kbd><kbd class="key-ctrl" data-v-baa3be99>Ctrl</kbd><kbd data-v-baa3be99>K</kbd></span></button><button type="button" class="VPNavBarAskAiButton" aria-label="Ask AI" aria-keyshortcuts="control+i meta+i" data-v-2fc7f2c6 data-v-4eb17e89><span class="vpi-sparkles" aria-hidden="true" data-v-4eb17e89></span></button><!----><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-9ca1369d data-v-7b3e138d><span id="main-nav-aria-label" class="visually-hidden" data-v-7b3e138d> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/zh/guide/" tabindex="0" data-v-7b3e138d data-v-6500c4c4><!--[--><span data-v-6500c4c4>构建指南</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/zh/develop/" tabindex="0" data-v-7b3e138d data-v-6500c4c4><!--[--><span data-v-6500c4c4>开发者</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/zh/contributing/" tabindex="0" data-v-7b3e138d data-v-6500c4c4><!--[--><span data-v-6500c4c4>贡献</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/zh/faq/" tabindex="0" data-v-7b3e138d data-v-6500c4c4><!--[--><span data-v-6500c4c4>FAQ</span><!--]--></a><!--]--><!--[--><div class="VPFlyout VPNavBarMenuGroup" data-v-7b3e138d data-v-42cb505d><button type="button" class="button" aria-haspopup="true" aria-expanded="false" data-v-42cb505d><span class="text" data-v-42cb505d><!----><span data-v-42cb505d>v3 (alpha)</span><span class="vpi-chevron-down text-icon" data-v-42cb505d></span></span></button><div class="menu" data-v-42cb505d><div class="VPMenu" data-v-42cb505d data-v-25a6cce8><div class="items" data-v-25a6cce8><!--[--><!--[--><div class="VPMenuLink" data-v-25a6cce8 data-v-fff73daa><a class="VPLink link" href="/zh/" data-v-fff73daa><!--[--><span data-v-fff73daa>v3 (alpha)</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-25a6cce8 data-v-fff73daa><a class="VPLink link" href="https://static-php.github.io/v2-docs/" data-v-fff73daa><!--[--><span data-v-fff73daa>v2</span><!--]--></a></div><!--]--><!--]--></div><!--[--><!--]--></div></div></div><!--]--><!--]--></nav><div class="VPFlyout VPNavBarTranslations translations" data-v-9ca1369d data-v-c70a0580 data-v-42cb505d><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="Change language" data-v-42cb505d><span class="text" data-v-42cb505d><span class="vpi-languages option-icon" data-v-42cb505d></span><!----><span class="vpi-chevron-down text-icon" data-v-42cb505d></span></span></button><div class="menu" data-v-42cb505d><div class="VPMenu" data-v-42cb505d data-v-25a6cce8><!----><!--[--><!--[--><div class="items" data-v-c70a0580><p class="title" data-v-c70a0580>简体中文</p><!--[--><div class="V
<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:#62687b;--shiki-dark:#818e99;"># 执行脚本</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:#62687b;--shiki-dark:#818e99;"># 交互模式</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:#e1
<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:#62687b;--shiki-dark:#818e99;"># 指定配置文件启动</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:#62687b;--shiki-dark:#818e99;"># 测试配置文件</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:#c62739;--shiki-dark:#F97583;">server</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#c62739;--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:#c62739;--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:#c62739;--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:#c62739;--shiki-dark:#F97583;"> location</span><span style="--shiki-light:#c62739;--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:#c62739;--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:#c62739;--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:#c62739;--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:#c62739;--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:#c62739;--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:#c62739;--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:#c62739;--shiki-dark:#F97583;">pm</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> = dynamic</span></span>
<span class="line"><span style="--shiki-light:#c62739;--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:#c62739;--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:#c62739;--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:#c62739;--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:#62687b;--shiki-dark:#818e99;"># 打包 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:#c62739;--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:#62687b;--shiki-dark:#818e99;"># 打包 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:#62687b;--shiki-dark:#818e99;"># 通过命令行参数注入(-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:#62687b;--shiki-dark:#818e99;"># 通过 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><s
<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:#62687b;--shiki-dark:#818e99;"># 以 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:#62687b;--shiki-dark:#818e99;"># 运行 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:#c62739;--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></div></div></main><footer class="VPDocFooter" data-v-7011f0d8 data-v-e29034c6><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-e29034c6><span class="visually-hidden" id="doc-footer-aria-label" data-v-e29034c6>Pager</span><div class="pager" data-v-e29034c6><a class="VPLink link pager-link prev" href="/zh/guide/first-build.html" data-v-e29034c6><!--[--><span class="desc" data-v-e29034c6>Previous page</span><span class="title" data-v-e29034c6>第一次构建</span><!--]--></a></div><div class="pager" data-v-e29034c6><a class="VPLink link pager-link next" href="/zh/guide/cli-reference.html" data-v-e29034c6><!--[--><span class="desc" data-v-e29034c6>Next page</span><span class="title" data-v-e29034c6>命令行参考</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-0cf61682 data-v-c3855bb3><div class="container" data-v-c3855bb3><p class="message
<script>window.__VP_HASH_MAP__=JSON.parse("{\"deps-craft-yml.md\":\"BlUAUDy4\",\"en_contributing_index.md\":\"DJrK0rwl\",\"en_develop_artifact-model.md\":\"CSsy1IGq\",\"en_develop_build-lifecycle.md\":\"DAZqcB7z\",\"en_develop_craft-yml.md\":\"KSoZofRA\",\"en_develop_doctor-module.md\":\"ByvES-_A\",\"en_develop_extending_annotations.md\":\"UKL7B7B3\",\"en_develop_extending_custom-artifact.md\":\"DotD8ITd\",\"en_develop_extending_dependency-injection.md\":\"CyyHOkvH\",\"en_develop_extending_index.md\":\"B2xj8d9p\",\"en_develop_extending_lifecycle-hooks.md\":\"6uwWcfAD\",\"en_develop_extending_package-classes.md\":\"y3Xf7UZ4\",\"en_develop_index.md\":\"BITZJqcR\",\"en_develop_package-model.md\":\"CMZBu01x\",\"en_develop_php-src-changes.md\":\"Cc0fC8cE\",\"en_develop_registry.md\":\"BsjJNDQv\",\"en_develop_structure.md\":\"D8gP8oQJ\",\"en_develop_system-build-tools.md\":\"CUw5wQ4E\",\"en_faq_index.md\":\"BvIAh2aW\",\"en_guide_cli-generator.md\":\"C6SB8xhE\",\"en_guide_cli-reference.md\":\"D7EY77fp\",\"en_guide_deps-map.md\":\"DKgvqXtD\",\"en_guide_env-vars.md\":\"BgjYKJG9\",\"en_guide_extension-notes.md\":\"B3shjkUU\",\"en_guide_extensions.md\":\"ATwZq3HB\",\"en_guide_first-build.md\":\"INdBGOsG\",\"en_guide_index.md\":\"z0D1Gcrs\",\"en_guide_installation.md\":\"BV9Ks-lX\",\"en_guide_migrate-from-v2.md\":\"CUFkYufx\",\"en_guide_sapi-reference.md\":\"p2zEyiLe\",\"en_guide_troubleshooting.md\":\"DVi8H9ZX\",\"en_index.md\":\"D-9tNbNs\",\"index.md\":\"TfAAAF_x\",\"zh_contributing_index.md\":\"8SUl40-w\",\"zh_develop_artifact-model.md\":\"CrLRSeeY\",\"zh_develop_build-lifecycle.md\":\"DLh_YUAK\",\"zh_develop_craft-yml.md\":\"uyL3P4FG\",\"zh_develop_doctor-module.md\":\"B-KVjOyS\",\"zh_develop_extending_annotations.md\":\"Dcz6J_X-\",\"zh_develop_extending_custom-artifact.md\":\"BoYCxDEr\",\"zh_develop_extending_dependency-injection.md\":\"BKeBJfDY\",\"zh_develop_extending_index.md\":\"B7wWMbKy\",\"zh_develop_extending_lifecycle-hooks.md\":\"CG51Rugr\",\"zh_develop_extending_package-classes.md\":\"DBU2hT9_\",\"zh_develop_index.md\":\"CrUwzvi2\",\"zh_develop_package-model.md\":\"DDw9ZCCd\",\"zh_develop_php-src-changes.md\":\"artDuYna\",\"zh_develop_registry.md\":\"ChqnXzVM\",\"zh_develop_structure.md\":\"BivWsi6C\",\"zh_develop_system-build-tools.md\":\"BLdfbezU\",\"zh_faq_index.md\":\"ypwV8ySx\",\"zh_guide_cli-generator.md\":\"BuKsNlwB\",\"zh_guide_cli-reference.md\":\"LVzdkmu2\",\"zh_guide_deps-map.md\":\"9-QWHshB\",\"zh_guide_env-vars.md\":\"D2oUaqNR\",\"zh_guide_extension-notes.md\":\"D9lGXhKW\",\"zh_guide_extensions.md\":\"CNtRfejb\",\"zh_guide_first-build.md\":\"DSwF9CHy\",\"zh_guide_index.md\":\"DR1hBcxc\",\"zh_guide_installation.md\":\"CWZRSBwL\",\"zh_guide_migrate-from-v2.md\":\"Dp7VZbGT\",\"zh_guide_sapi-reference.md\":\"TjYI_FdR\",\"zh_guide_troubleshooting.md\":\"CJ6N_2fk\",\"zh_index.md\":\"BXvgifjq\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"StaticPHP\",\"description\":\"A powerful tool designed for building portable executables including PHP, extensions, and more.\",\"base\":\"/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/images/static-php_nobg.png\",\"nav\":[],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/crazywhalecc/static-php-cli\"}],\"footer\":{\"message\":\"Released under the MIT License.\",\"copyright\":\"Copyright © 2023-present crazywhalecc\"},\"externalLinkIcon\":true,\"search\":{\"provider\":\"algolia\",\"options\":{\"appId\":\"IHJHUB1SF1\",\"apiKey\":\"8266d31cc2ffbd0e059f1c6e5bdaf8fc\",\"indexName\":\"static-php docs\",\"askAi\":{\"assistantId\":\"b72369b2-60a5-461d-902c-5c18d8c05902\",\"agentStudio\":true,\"sidePanel\":true}}}},\"locales\":{\"en\":{\"label\":\"English\",\"lang\":\"en\",\"themeConfig\":{\"nav\":[{\"text\":\"Guide\",\"link\":\"/en/guide/\"},{\"text\":\"Develop\",\"link\":\"/en/develop/\"},{\"text\":\"Contributing\",\"link\":\"/en/contributing/\"},{\"text\":\"FAQ\",\"link\":\"/en/faq/\"},{\"text\":\"v3 (alpha)\",\"items\":[{\"text\":\"v3 (alpha)\",\"link\":\"/en/\
</body>
</html>