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.12">
<link rel="preload stylesheet" href="/assets/style.DtFsVR9B.css" as="style">
<link rel="preload stylesheet" href="/vp-icons.css" as="style">
<script type="module" src="/assets/app.DFjSYdj3.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/theme.CtIPYXhG.js">
<link rel="modulepreload" href="/assets/chunks/framework.C2AwuPrQ.js">
<link rel="modulepreload" href="/assets/zh_guide_sapi-reference.md.DXv5eV6I.lean.js">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a: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-1df9f90f><!--[--><!--]--><!--[--><span tabindex="-1" data-v-0b0ada53></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-0b0ada53>Skip to content</a><!--]--><!----><header class="VPNav" data-v-1df9f90f data-v-9f75dce3><div class="VPNavBar" data-v-9f75dce3 data-v-2a96a3d0><div class="wrapper" data-v-2a96a3d0><div class="container" data-v-2a96a3d0><div class="title" data-v-2a96a3d0><div class="VPNavBarTitle has-sidebar" data-v-2a96a3d0 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-2a96a3d0><div class="content-body" data-v-2a96a3d0><!--[--><!--]--><div class="VPNavBarSearch search" data-v-2a96a3d0><!--[--><!----><div id="docsearch"><button type="button" aria-label="Search" aria-keyshortcuts="/ control+k meta+k" class="DocSearch DocSearch-Button"><span class="DocSearch-Button-Container"><span class="vpi-search DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key"></kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-2a96a3d0 data-v-39714824><span id="main-nav-aria-label" class="visually-hidden" data-v-39714824> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/zh/guide/" tabindex="0" data-v-39714824 data-v-e56f3d57><!--[--><span data-v-e56f3d57>构建指南</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/zh/develop/" tabindex="0" data-v-39714824 data-v-e56f3d57><!--[--><span data-v-e56f3d57>开发者</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/zh/contributing/" tabindex="0" data-v-39714824 data-v-e56f3d57><!--[--><span data-v-e56f3d57>贡献</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/zh/faq/" tabindex="0" data-v-39714824 data-v-e56f3d57><!--[--><span data-v-e56f3d57>FAQ</span><!--]--></a><!--]--><!--[--><div class="VPFlyout VPNavBarMenuGroup" data-v-39714824 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-cd834e02><a class="VPLink link" href="/zh/" data-v-cd834e02><!--[--><span data-v-cd834e02>v3 (alpha)</span><!--]--></a></div><!--]--><!--[--><div class="VPMenuLink" data-v-25a6cce8 data-v-cd834e02><a class="VPLink link vp-external-link-icon" href="https://static-php.github.io/v2-docs/" target="_blank" rel="noreferrer" data-v-cd834e02><!--[--><span data-v-cd834e02>v2</span><!--]--></a></div><!--]--><!--]--></div><!--[--><!--]--></div></div></div><!--]--><!--]--></nav><div class="VPFlyout VPNavBarTranslations translations" data-v-2a96a3d0 data-v-88af2de4 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-88af2de4><p class="title" data-v-88af2de4>简体中文</p><!--[--><div class="VPMenuLink" data-v-88af2de4 data-v-cd834e02><a class="VPLink link" href="/en/guide/sapi-reference.html" data-v-cd834e02><!--[--><span data-v-cd834e02>English</span><!--]--></a></div><!--]--></div><!--]--><!--]-->
<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:#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:#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><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:#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></div></div></main><footer class="VPDocFooter" data-v-7011f0d8 data-v-e257564d><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-e257564d><span class="visually-hidden" id="doc-footer-aria-label" data-v-e257564d>Pager</span><div class="pager" data-v-e257564d><a class="VPLink link pager-link prev" href="/zh/guide/first-build.html" data-v-e257564d><!--[--><span class="desc" data-v-e257564d>Previous page</span><span class="title" data-v-e257564d>第一次构建</span><!--]--></a></div><div class="pager" data-v-e257564d><a class="VPLink link pager-link next" href="/zh/guide/cli-reference.html" data-v-e257564d><!--[--><span class="desc" data-v-e257564d>Next page</span><span class="title" data-v-e257564d>命令行参考</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><footer class="VPFooter has-sidebar" data-v-1df9f90f data-v-c3855bb3><div class="container" data-v-c3855bb3><p class="message
<script>window.__VP_HASH_MAP__=JSON.parse("{\"deps-craft-yml.md\":\"DaRp5sDR\",\"en_contributing_index.md\":\"Bw6aGZo7\",\"en_develop_artifact-model.md\":\"Be9wN_ZU\",\"en_develop_build-lifecycle.md\":\"BrkkrOI9\",\"en_develop_craft-yml.md\":\"CJqlRAWM\",\"en_develop_doctor-module.md\":\"BPx_gh7b\",\"en_develop_extending_annotations.md\":\"rWEgD5t7\",\"en_develop_extending_custom-artifact.md\":\"BQoftnUi\",\"en_develop_extending_dependency-injection.md\":\"3RvnsJs8\",\"en_develop_extending_index.md\":\"CBALgGvM\",\"en_develop_extending_lifecycle-hooks.md\":\"TH51ajMN\",\"en_develop_extending_package-classes.md\":\"DL47sxq4\",\"en_develop_index.md\":\"CDPdLdXm\",\"en_develop_package-model.md\":\"D5wiXvya\",\"en_develop_php-src-changes.md\":\"CIUUevPf\",\"en_develop_registry.md\":\"B5tf5XnG\",\"en_develop_structure.md\":\"B3aY4J4P\",\"en_develop_system-build-tools.md\":\"aR6vgJMi\",\"en_faq_index.md\":\"ButqLRAC\",\"en_guide_cli-generator.md\":\"Bh1mnldB\",\"en_guide_cli-reference.md\":\"B6zUxFdM\",\"en_guide_deps-map.md\":\"B9M0h5GJ\",\"en_guide_env-vars.md\":\"B5JOZL1S\",\"en_guide_extension-notes.md\":\"C1QFg1E9\",\"en_guide_extensions.md\":\"CYT0fXgd\",\"en_guide_first-build.md\":\"C3LOd79t\",\"en_guide_index.md\":\"Chrx4Kg2\",\"en_guide_installation.md\":\"DNcSrgIL\",\"en_guide_migrate-from-v2.md\":\"CfVymFnT\",\"en_guide_sapi-reference.md\":\"Dx3FnmW6\",\"en_guide_troubleshooting.md\":\"Mc4ZUzP-\",\"en_index.md\":\"CZz4hp1l\",\"index.md\":\"DlohUUjo\",\"zh_contributing_index.md\":\"BxNPLW0M\",\"zh_develop_artifact-model.md\":\"BtcNBk1j\",\"zh_develop_build-lifecycle.md\":\"D1JbjvDB\",\"zh_develop_craft-yml.md\":\"oQn7yY_F\",\"zh_develop_doctor-module.md\":\"DAzJoWwn\",\"zh_develop_extending_annotations.md\":\"DAa7FG7j\",\"zh_develop_extending_custom-artifact.md\":\"BTEWH7KO\",\"zh_develop_extending_dependency-injection.md\":\"PLkrv44m\",\"zh_develop_extending_index.md\":\"B478Mpx4\",\"zh_develop_extending_lifecycle-hooks.md\":\"BNdlHrBu\",\"zh_develop_extending_package-classes.md\":\"CLofM-pE\",\"zh_develop_index.md\":\"CYr92Q4h\",\"zh_develop_package-model.md\":\"DYRZ8aaf\",\"zh_develop_php-src-changes.md\":\"QIFUEZHE\",\"zh_develop_registry.md\":\"BvRBmoGT\",\"zh_develop_structure.md\":\"EpUhxfrR\",\"zh_develop_system-build-tools.md\":\"DEEE1raf\",\"zh_faq_index.md\":\"DkTldA8b\",\"zh_guide_cli-generator.md\":\"Djvjm7dZ\",\"zh_guide_cli-reference.md\":\"DMttieGz\",\"zh_guide_deps-map.md\":\"BsudOLor\",\"zh_guide_env-vars.md\":\"Bs72W99k\",\"zh_guide_extension-notes.md\":\"D-KMlaiu\",\"zh_guide_extensions.md\":\"CdF_j2fu\",\"zh_guide_first-build.md\":\"CQdFhKsg\",\"zh_guide_index.md\":\"B1jsb7XJ\",\"zh_guide_installation.md\":\"Ap2snxXu\",\"zh_guide_migrate-from-v2.md\":\"Df8wnmfP\",\"zh_guide_sapi-reference.md\":\"DXv5eV6I\",\"zh_guide_troubleshooting.md\":\"CueHHZkW\",\"zh_index.md\":\"CkWIeJB6\"}");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>