mirror of
https://github.com/crazywhalecc/static-php-cli.git
synced 2026-07-07 16:55:38 +08:00
Add GUIDE section for v3 docs
This commit is contained in:
crazywhalecc
@@ -2,6 +2,10 @@
|
||||
aside: false
|
||||
---
|
||||
|
||||
<script setup>
|
||||
import CliGenerator from "../../.vitepress/components/CliGenerator.vue";
|
||||
</script>
|
||||
|
||||
# 编译命令生成器
|
||||
|
||||
<!-- TODO: 嵌入 CliGenerator Vue 组件。 -->
|
||||
<CliGenerator lang="zh" />
|
||||
|
||||
@@ -1,6 +1,212 @@
|
||||
---
|
||||
outline: 'deep'
|
||||
---
|
||||
|
||||
# 命令行参考
|
||||
|
||||
<!-- TODO: 所有 spc 命令和选项的完整参考。
|
||||
每个命令一个 ## 小节：download、build、craft、doctor、check-update、dev:*。
|
||||
每个选项：类型、默认值、说明、示例。
|
||||
涵盖平台专属选项（如 Windows 下的 --embed-icon）。 -->
|
||||
::: tip
|
||||
如果你采用的是 spc 二进制方式安装，请将本章节中的所有 `spc` 替换为 `./spc` 或 `.\spc.exe`。
|
||||
|
||||
如果你采用的是源码安装，请将 `spc` 替换为 `bin/spc`。
|
||||
:::
|
||||
|
||||
## download
|
||||
|
||||
下载构建所需的源码包和预编译二进制。
|
||||
|
||||
```bash
|
||||
spc download [artifacts] [options]
|
||||
```
|
||||
|
||||
`artifacts`（可选）：指定要下载的制品名称，逗号分隔（如 `"php-src,openssl,curl"`）。
|
||||
|
||||
### 选项
|
||||
|
||||
| 选项 | 缩写 | 说明 |
|
||||
|---|---|---|
|
||||
| `--for-extensions=<list>` | `-e` | 按扩展名下载其所需的制品 |
|
||||
| `--for-libs=<list>` | `-l` | 按库名下载其所需的制品 |
|
||||
| `--for-packages=<list>` | | 按包名下载其所需的制品 |
|
||||
| `--without-suggests` | | 使用 `--for-extensions` 时跳过建议包 |
|
||||
| `--clean` | | 下载前删除旧的下载缓存 |
|
||||
| `--with-php=<ver>` | | PHP 版本，格式为 `major.minor`（默认 `8.4`）|
|
||||
| `--prefer-binary` | `-p` | 优先使用预编译二进制 |
|
||||
| `--prefer-source` | | 优先使用源码包 |
|
||||
| `--source-only` | | 仅下载源码制品 |
|
||||
| `--binary-only` | | 仅下载二进制制品 |
|
||||
| `--parallel=<n>` | `-P` | 并行下载数（默认 `1`）|
|
||||
| `--retry=<n>` | `-R` | 失败重试次数（默认 `0`）|
|
||||
| `--ignore-cache=<list>` | | 强制重新下载指定制品 |
|
||||
| `--no-alt` | | 不使用镜像站 |
|
||||
| `--no-shallow-clone` | | 不使用浅层克隆 |
|
||||
| `--custom-url=<src:url>` | `-U` | 覆盖指定源的下载地址 |
|
||||
| `--custom-git=<src:branch:url>` | `-G` | 覆盖为自定义 git 仓库 |
|
||||
| `--custom-local=<src:path>` | `-L` | 使用本地路径作为制品来源 |
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# 按扩展名下载（推荐）
|
||||
spc download --for-extensions="bcmath,openssl,curl" --with-php=8.4
|
||||
|
||||
# 下载指定制品
|
||||
spc download "php-src,openssl"
|
||||
|
||||
# 增加并行数和重试次数
|
||||
spc download --for-extensions="bcmath,openssl,curl" --parallel 8 --retry=3
|
||||
|
||||
# 优先使用预编译二进制
|
||||
spc download --for-extensions="bcmath,openssl,curl" --prefer-binary
|
||||
|
||||
# 强制重新下载 PHP 源码（如切换版本）
|
||||
spc download --for-extensions="bcmath,curl" --ignore-cache="php-src" --with-php=8.3
|
||||
|
||||
# 覆盖下载地址
|
||||
spc download --for-extensions="bcmath" --custom-url "php-src:https://downloads.php.net/~user/php-8.5.0alpha1.tar.xz"
|
||||
```
|
||||
|
||||
## build:php {#build-php}
|
||||
|
||||
从源码编译 PHP 及扩展。别名：`build`。
|
||||
|
||||
```bash
|
||||
spc build:php <extensions> [options]
|
||||
```
|
||||
|
||||
`extensions`（必填）：要静态编译的扩展名列表，逗号分隔（如 `"bcmath,openssl,curl"`）。
|
||||
|
||||
`build:php` 上也可使用所有 `download` 选项，只需加上 `--dl-` 前缀（如 `--dl-with-php=8.3`、`--dl-parallel=4`），这些参数将传递给构建前自动运行的下载器。
|
||||
|
||||
### SAPI 选择 {#sapi-selection}
|
||||
|
||||
以下选项仅适用于 `build:php` 组合目标。如需单独构建某个 SAPI，请使用对应的专用命令（如 `spc build:php-cli`）。
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--build-cli` | 构建 `cli` SAPI（`php` / `php.exe`）|
|
||||
| `--build-fpm` | 构建 `php-fpm`（仅 Linux 和 macOS）|
|
||||
| `--build-cgi` | 构建 `php-cgi` |
|
||||
| `--build-micro` | 构建 `micro.sfx` |
|
||||
| `--build-embed` | 构建 embed 静态库（`libphp.a` / `php8embed.lib`）|
|
||||
| `--build-frankenphp` | 构建 FrankenPHP 二进制 |
|
||||
|
||||
### 通用构建选项 {#common-build-options}
|
||||
|
||||
| 选项 | 缩写 | 说明 |
|
||||
|---|---|---|
|
||||
| `--no-strip` | | 保留调试符号，不精简二进制 |
|
||||
| `--with-upx-pack` | | 用 UPX 压缩产物（需先 `spc install-pkg upx`；仅 Linux 和 Windows）|
|
||||
| `--disable-opcache-jit` | | 禁用 OPcache JIT |
|
||||
| `--with-config-file-path=<path>` | | PHP 查找 `php.ini` 的目录（默认：`/usr/local/etc/php`）|
|
||||
| `--with-config-file-scan-dir=<path>` | | PHP 扫描追加 `.ini` 文件的目录（默认：`/usr/local/etc/php/conf.d`）|
|
||||
| `--with-hardcoded-ini=<k=v>` | `-I` | 编译时将 INI 配置硬编码进二进制（可重复使用）|
|
||||
| `--enable-zts` | | 启用线程安全（ZTS）模式 |
|
||||
| `--no-smoke-test` | | 跳过构建后的冒烟测试 |
|
||||
| `--with-suggests` | `-L` / `-E` | 同时解析并安装建议包 |
|
||||
| `--with-packages=<list>` | | 额外安装的包 |
|
||||
| `--no-download` | | 跳过下载步骤（使用已有缓存）|
|
||||
| `--with-added-patch=<file>` | `-P` | 注入外部 PHP 补丁脚本（可重复使用）|
|
||||
| `--build-shared=<list>` | `-D` | 指定编译为共享 `.so` / `.dll` 的扩展 |
|
||||
|
||||
### micro 专用选项 {#micro-options}
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--with-micro-fake-cli` | 让 `micro` 的 `PHP_SAPI` 报告为 `cli` 而非 `micro` |
|
||||
| `--without-micro-ext-test` | 跳过构建后的 `micro.sfx` 扩展测试 |
|
||||
| `--with-micro-logo=<path>` | 为 `micro.sfx` 嵌入自定义 `.ico` 图标（仅 Windows）|
|
||||
| `--enable-micro-win32` | 将 `micro.sfx` 构建为 Win32 GUI 程序而非控制台程序（仅 Windows）|
|
||||
|
||||
### frankenphp 专用选项 {#frankenphp-options}
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--enable-zts` | FrankenPHP 必须开启线程安全 |
|
||||
| `--with-frankenphp-app=<path>` | 将指定目录嵌入到 FrankenPHP 二进制中 |
|
||||
|
||||
### embed 专用选项 {#embed-options}
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--build-shared=<list>` | 将指定扩展编译为共享库（需要 embed SAPI）|
|
||||
|
||||
### 下载透传选项 {#download-options}
|
||||
|
||||
所有下载器选项均可加 `--dl-` 前缀使用：
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--dl-with-php=<ver>` | 指定下载的 PHP 版本（默认 `8.4`）|
|
||||
| `--dl-prefer-binary` | 优先使用预编译二进制依赖 |
|
||||
| `--dl-parallel=<n>` | 并行下载数 |
|
||||
| `--dl-retry=<n>` | 失败重试次数 |
|
||||
| `--dl-custom-url=<src:url>` | 覆盖指定源的下载地址 |
|
||||
| `--dl-custom-git=<src:branch:url>` | 覆盖为自定义 git 仓库 |
|
||||
|
||||
### 示例
|
||||
|
||||
```bash
|
||||
# 构建 cli SAPI
|
||||
spc build:php "bcmath,openssl,curl" --build-cli
|
||||
|
||||
# 同时构建 cli + micro
|
||||
spc build:php "bcmath,phar,openssl,curl" --build-cli --build-micro
|
||||
|
||||
# 指定 PHP 版本
|
||||
spc build:php "bcmath,openssl" --build-cli --dl-with-php=8.3
|
||||
|
||||
# 硬编码 INI 到二进制
|
||||
spc build:php "bcmath,pcntl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
|
||||
|
||||
# 保留调试符号
|
||||
spc build:php "bcmath,openssl" --build-cli --no-strip
|
||||
|
||||
# 构建 FrankenPHP（需开启 ZTS）
|
||||
spc build:php "bcmath,openssl,curl" --build-frankenphp --enable-zts
|
||||
```
|
||||
|
||||
## build:php-cli, build:php-fpm, build:php-micro, build:php-embed, build:php-cgi, build:frankenphp
|
||||
|
||||
专用单目标构建命令，接受与 `build:php` 相同的选项，但不需要 SAPI 选择标志（`--build-*`），目标已隐式确定。
|
||||
|
||||
```bash
|
||||
spc build:php-cli "bcmath,openssl,curl"
|
||||
spc build:php-micro "bcmath,phar,openssl"
|
||||
spc build:php-fpm "bcmath,openssl,curl,pdo_mysql"
|
||||
spc build:php-embed "bcmath,openssl"
|
||||
spc build:frankenphp "bcmath,openssl,curl" --enable-zts
|
||||
```
|
||||
|
||||
## craft
|
||||
|
||||
读取 `craft.yml` 并自动完成全流程构建。
|
||||
|
||||
```bash
|
||||
spc craft [path/to/craft.yml]
|
||||
```
|
||||
|
||||
未指定路径时，使用当前工作目录下的 `craft.yml`。配置格式参见 [craft.yml 配置](../develop/craft-yml)。
|
||||
|
||||
## doctor
|
||||
|
||||
检查当前环境是否满足编译要求。
|
||||
|
||||
```bash
|
||||
spc doctor [--auto-fix[=never]]
|
||||
```
|
||||
|
||||
| 选项 | 说明 |
|
||||
|---|---|
|
||||
| `--auto-fix` | 自动修复检测到的问题（使用系统包管理器）|
|
||||
| `--auto-fix=never` | 仅报告问题，不尝试自动修复 |
|
||||
|
||||
## dev:shell
|
||||
|
||||
进入加载了 StaticPHP 构建环境的交互式 Shell（编译器 wrapper、`buildroot/`、`pkgroot/` 等均已添加到 `PATH`）。
|
||||
|
||||
```bash
|
||||
spc dev:shell
|
||||
```
|
||||
|
||||
可用于在 embed SAPI 的 `libphp.a` 上编译小型 C 程序，或手动检查构建环境。
|
||||
|
||||
|
||||
@@ -1,4 +1,51 @@
|
||||
# 环境变量
|
||||
|
||||
<!-- TODO: config/env.ini 和 config/env.custom.ini 支持的所有环境变量完整表格。
|
||||
从 v2 env-vars.md 迁移并更新。 -->
|
||||
本页面的环境变量列表中所提到的所有环境变量都具有默认值，除非另有说明。你可以通过设置这些环境变量来覆盖默认值。
|
||||
|
||||
## 环境变量列表
|
||||
|
||||
StaticPHP 将环境变量集中到了 `config/env.ini` 文件中，你可以通过修改这个文件来设置环境变量。
|
||||
|
||||
我们将 StaticPHP 支持的环境变量分为三种：
|
||||
|
||||
- **全局内部环境变量**：在 StaticPHP 启动后即声明，你可以在 StaticPHP 的内部使用 `getenv()` 来获取他们，也可以在启动 StaticPHP 前覆盖。
|
||||
- **固定环境变量**：在 StaticPHP 启动后声明，你仅可使用 `getenv()` 获取，但无法通过 shell 脚本对其覆盖。
|
||||
- **配置文件环境变量**：在 StaticPHP 构建前声明，你可以通过修改 `config/env.ini` 文件或通过 shell 脚本来设置这些环境变量。
|
||||
|
||||
你可以阅读 [config/env.ini](https://github.com/crazywhalecc/static-php-cli/blob/v3/config/env.ini) 中每项参数的注释来了解其作用（仅限英文版）。
|
||||
|
||||
## 自定义环境变量
|
||||
|
||||
一般情况下，你不需要修改任何以下环境变量，因为它们已经被设置为最佳值。
|
||||
但是，如果你有特殊需求，你可以通过设置这些环境变量来满足你的需求（比如你需要调试不同编译参数下的 PHP 性能表现）。
|
||||
|
||||
如需使用自定义环境变量，你可以在终端中使用 `export` 命令或者在命令前直接设置环境变量，例如：
|
||||
|
||||
```shell
|
||||
# export 方式
|
||||
export SPC_CONCURRENCY=4
|
||||
spc build:php "mbstring,pcntl" --build-cli
|
||||
|
||||
# 直接设置方式
|
||||
SPC_CONCURRENCY=4 spc build:php "mbstring,pcntl" --build-cli
|
||||
```
|
||||
|
||||
或者，如果你需要长期修改某个环境变量，你可以通过修改 `config/env.ini` 文件来实现。
|
||||
|
||||
`config/env.ini` 分为三段，其中 `[global]` 全局有效，`[windows]`、`[macos]`、`[linux]` 仅对应的操作系统有效。
|
||||
|
||||
例如，你需要修改编译 PHP 的 `./configure` 命令，你可以在 `config/env.ini` 文件中找到 `SPC_CMD_PREFIX_PHP_CONFIGURE` 环境变量，然后修改其值即可。
|
||||
|
||||
但如果你的构建条件比较复杂，需要多种 env.ini 进行切换，我们推荐你使用 `config/env.custom.ini` 文件，这样你可以在不修改默认的 `config/env.ini` 文件的情况下，
|
||||
通过写入额外的重载项目指定你的环境变量。
|
||||
|
||||
```ini
|
||||
; This is an example of `config/env.custom.ini` file,
|
||||
; we modify the `SPC_CONCURRENCY` and linux default CFLAGS passing to libs and PHP
|
||||
[global]
|
||||
SPC_CONCURRENCY=4
|
||||
|
||||
[linux]
|
||||
SPC_DEFAULT_C_FLAGS="-O3"
|
||||
```
|
||||
|
||||
|
||||
@@ -1,3 +1,159 @@
|
||||
# 扩展注意事项
|
||||
|
||||
<!-- TODO: 从 v2 extension-notes.md 迁移并更新。各扩展编译特殊说明。 -->
|
||||
因为是静态编译，扩展不会 100% 完美编译，而且不同扩展对 PHP、环境都有不同的要求，这里将一一列举。
|
||||
|
||||
## curl
|
||||
|
||||
HTTP3 支持默认未启用，需在编译时添加 `--with-libs="nghttp2,nghttp3,ngtcp2"` 以启用 PHP 8.4 及以上版本的 HTTP3 支持。
|
||||
|
||||
使用 curl 请求 HTTPS 时，可能存在 `error:80000002:system library::No such file or directory` 错误，
|
||||
解决办法详见 [FAQ](../faq/)。
|
||||
|
||||
## phpmicro
|
||||
|
||||
1. phpmicro SAPI 仅支持 PHP >= 8.0 版本。
|
||||
|
||||
## swoole
|
||||
|
||||
1. swoole >= 5.0 版本仅支持 PHP >= 8.0 版本。
|
||||
2. swoole 目前不支持 PHP 8.0 版本 curl 的 hook（后续有可能会修复）。
|
||||
3. 编译时只包含 `swoole` 扩展时不会完整开启支持的 Swoole 数据库协程 hook，如需使用请加入对应的 `swoole-hook-xxx` 扩展。
|
||||
4. swoole 在部分扩展组合下可能出现 `zend_mm_heap corrupted` 问题，暂未找到是什么原因导致的。
|
||||
|
||||
## swoole-hook-pgsql
|
||||
|
||||
swoole-hook-pgsql 不是一个扩展，而是 Swoole 的 Hook 特性。
|
||||
如果你在编译时添加了 `swoole,swoole-hook-pgsql`，你将启用 Swoole 的 PostgreSQL 客户端和 `pdo_pgsql` 扩展的协程模式。
|
||||
|
||||
swoole-hook-pgsql 与 `pdo_pgsql` 扩展冲突。如需使用 Swoole 和 `pdo_pgsql`，请删除 pdo_pgsql 扩展，启用 `swoole` 和 `swoole-hook-pgsql` 即可。
|
||||
该扩展包含了 `pdo_pgsql` 的协程环境的实现。
|
||||
|
||||
在 macOS 系统，`pdo_pgsql` 可能无法正常连接到 postgresql 服务器，请谨慎使用。
|
||||
|
||||
## swoole-hook-mysql
|
||||
|
||||
swoole-hook-mysql 不是一个扩展，而是 Swoole 的 Hook 特性。
|
||||
如果你在编译时添加了 `swoole,swoole-hook-mysql`，你将启用 Swoole 的 `mysqlnd` 和 `pdo_mysql` 的协程模式。
|
||||
|
||||
## swoole-hook-sqlite
|
||||
|
||||
swoole-hook-sqlite 不是一个扩展，而是 Swoole 的 Hook 特性。
|
||||
如果你在编译时添加了 `swoole,swoole-hook-sqlite`，你将启用 Swoole 的 `pdo_sqlite` 的协程模式（Swoole 必须为 5.1 以上）。
|
||||
|
||||
swoole-hook-sqlite 与 `pdo_sqlite` 扩展冲突。如需使用 Swoole 和 `pdo_sqlite`，请删除 pdo_sqlite 扩展，启用 `swoole` 和 `swoole-hook-sqlite` 即可。
|
||||
该扩展包含了 `pdo_sqlite` 的协程环境的实现。
|
||||
|
||||
## swoole-hook-odbc
|
||||
|
||||
swoole-hook-odbc 不是一个扩展，而是 Swoole 的 Hook 特性。
|
||||
如果你在编译时添加了 `swoole,swoole-hook-odbc`，你将启用 Swoole 的 `odbc` 扩展的协程模式。
|
||||
|
||||
swoole-hook-odbc 与 `pdo_odbc` 扩展冲突。如需使用 Swoole 和 `pdo_odbc`，请删除 `pdo_odbc` 扩展，启用 `swoole` 和 `swoole-hook-odbc` 即可。
|
||||
该扩展包含了 `pdo_odbc` 的协程环境的实现。
|
||||
|
||||
## swow
|
||||
|
||||
1. swow 仅支持 PHP 8.0+ 版本。
|
||||
|
||||
## imagick
|
||||
|
||||
1. OpenMP 支持已被禁用，这是维护者推荐的做法，系统软件包也是如此配置。
|
||||
|
||||
## imap
|
||||
|
||||
1. 该扩展目前不支持 Kerberos。
|
||||
2. 由于底层的 c-client、ext-imap 不是线程安全的。无法在 `--enable-zts` 构建中使用它。
|
||||
3. 该扩展已在 PHP 8.4 中被移除，因此我们建议您寻找替代实现，例如 [Webklex/php-imap](https://github.com/Webklex/php-imap)。
|
||||
|
||||
## gd
|
||||
|
||||
1. gd 扩展依赖了较多的额外图形库，默认情况下，直接使用 `bin/spc build gd` 不会引入和支持部分图形库，例如 `libjpeg`、`libavif` 等，
|
||||
需要使用 `--with-libs` 参数补全。目前支持 `freetype,libjpeg,libavif,libwebp` 四个库的支持，所以这里可以使用以下命令来让 gd 库引入它们：
|
||||
|
||||
```bash
|
||||
bin/spc build gd --with-libs=freetype,libjpeg,libavif,libwebp --build-cli
|
||||
```
|
||||
|
||||
## mcrypt
|
||||
|
||||
1. 目前未支持，未来也不计划支持此扩展。[#32](https://github.com/crazywhalecc/static-php-cli/issues/32)
|
||||
|
||||
## oci8
|
||||
|
||||
1. oci8 是 Oracle 数据库的扩展，因为 Oracle 提供的扩展所依赖的库未提供静态编译版本（`.a`）或源代码，无法使用静态链接的方式将此扩展编译到 php 内，故无法支持。
|
||||
|
||||
## xdebug
|
||||
|
||||
1. Xdebug 只能作为共享扩展进行构建。在 Linux 上，您需要使用 glibc 变体的 `SPC_TARGET`（例如 `native-native-gnu.2.17`），而不是默认的 musl 静态目标。
|
||||
2. 使用 Linux/glibc 或 macOS 时，您可以使用 `--build-shared=xdebug` 将 Xdebug 编译为共享扩展。
|
||||
编译后的 `./php` 二进制文件可以通过指定 INI 文件进行配置和运行，例如 `./php -d 'zend_extension=/path/to/xdebug.so' your-code.php`。
|
||||
|
||||
## xml
|
||||
|
||||
1. xml 包括 xmlreader、xmlwriter、dom、simplexml 等，添加 xml 扩展时最好同时启用这些扩展。
|
||||
2. libxml 包含在 xml 扩展中。启用 xml 相当于启用 libxml。
|
||||
|
||||
## glfw
|
||||
|
||||
1. glfw 扩展依赖 OpenGL，在 Linux 平台还依赖 X11 等环境，这些库都无法被轻易地静态链接。
|
||||
2. 在 macOS 系统下，我们可以动态链接系统的 OpenGL 和一些相关的库。
|
||||
|
||||
## rar
|
||||
|
||||
1. rar 扩展目前在 macOS x86_64 环境下与 `common` 扩展集合编译 phpmicro 存在问题。
|
||||
|
||||
## pgsql
|
||||
|
||||
~~pgsql ssl 连接与 openssl 3.2.0 不兼容。相关链接：~~
|
||||
|
||||
- ~~<https://github.com/Homebrew/homebrew-core/issues/155651>~~
|
||||
- ~~<https://github.com/Homebrew/homebrew-core/pull/155699>~~
|
||||
- ~~<https://github.com/postgres/postgres/commit/c82207a548db47623a2bfa2447babdaa630302b9>~~
|
||||
|
||||
pgsql 16.2 修复了这个 Bug，现在正常工作了。
|
||||
|
||||
在 pgsql 使用 SSL 连接时，可能存在 `error:80000002:system library::No such file or directory` 错误，
|
||||
解决办法详见 [FAQ](../faq/)。
|
||||
|
||||
## openssl
|
||||
|
||||
使用基于 openssl 的扩展（如 curl、pgsql 等网络库）时，可能存在 `error:80000002:system library::No such file or directory` 错误，
|
||||
解决办法详见 [FAQ](../faq/)。
|
||||
|
||||
## password-argon2
|
||||
|
||||
1. password-argon2 不是一个标准的扩展。`password_hash` 函数的 `PASSWORD_ARGON2ID` 算法需要 libsodium 或 libargon2 才能工作。
|
||||
2. 使用 password-argon2 可以为此启用多线程支持。
|
||||
|
||||
## ffi
|
||||
|
||||
1. 由于 musl libc 静态链接的限制，无法加载动态库，因此无法使用 ffi。
|
||||
如果您需要使用 ffi 扩展，请使用基于 glibc 的 `SPC_TARGET`（例如 `native-native-gnu.2.17`），详见 [SAPI 参考](./sapi-reference)。
|
||||
2. macOS 支持 ffi 扩展，但某些内核不包含调试符号时会出现错误。
|
||||
3. Windows x64 支持 ffi 扩展。
|
||||
|
||||
## xhprof
|
||||
|
||||
xhprof 扩展包含三部分：`xhprof_extension`、`xhprof_html`、`xhprof_libs`。编译的二进制中只包含 `xhprof_extension`。
|
||||
如果需要使用 xhprof，请到 [pecl.php.net/package/xhprof](http://pecl.php.net/package/xhprof) 下载源码，指定 `xhprof_libs` 和 `xhprof_html` 路径来使用。
|
||||
|
||||
## event
|
||||
|
||||
event 扩展在 macOS 系统下编译后暂无法使用 `openpty` 特性。相关 Issue：
|
||||
|
||||
- [static-php-cli#335](https://github.com/crazywhalecc/static-php-cli/issues/335)
|
||||
|
||||
## parallel
|
||||
|
||||
parallel 扩展只支持 PHP 8.0 及以上版本，并只支持 ZTS 构建（`--enable-zts`）。
|
||||
|
||||
## spx
|
||||
|
||||
1. SPX 目前不支持 Windows，且官方仓库也不支持静态编译，static-php-cli 使用了 [修改版本](https://github.com/static-php/php-spx)。
|
||||
|
||||
## mimalloc
|
||||
|
||||
1. 从技术上讲，这不是扩展，而是一个库。
|
||||
2. 在 Linux 或 macOS 上使用 `--with-libs="mimalloc"` 进行构建将覆盖默认分配器。
|
||||
3. 目前，这还处于实验阶段，但建议在线程环境中使用。
|
||||
|
||||
|
||||
@@ -1,3 +1,17 @@
|
||||
<script setup>
|
||||
import SearchTable from "../../.vitepress/components/SearchTable.vue";
|
||||
</script>
|
||||
|
||||
# 支持的扩展列表
|
||||
|
||||
<!-- TODO: 由 `bin/spc dev:gen-ext-docs` 自动生成。v3 命令实现后填充。 -->
|
||||
> - ✅: 已支持
|
||||
> - 空白: 目前还不支持，或正在支持中
|
||||
|
||||
<search-table />
|
||||
|
||||
::: tip
|
||||
如果缺少您需要的扩展，您可以创建 [功能请求](https://github.com/crazywhalecc/static-php-cli/issues)。
|
||||
|
||||
某些扩展或其依赖的库会有可选特性（例如 gd 可选支持 libwebp、freetype 等）。
|
||||
仅使用 `bin/spc build gd --build-cli` 不会包含这些可选依赖——StaticPHP 默认遵循最小依赖原则。
|
||||
:::
|
||||
|
||||
@@ -15,7 +15,7 @@ StaticPHP 提供两种构建方式，根据使用场景选择：
|
||||
| 方式 | 适合场景 |
|
||||
|--------------|--------------------------|
|
||||
| `craft` 一键构建 | 日常使用、快速上手 |
|
||||
| 分步构建 | CI/CD 流水线、需要拆分下载与编译阶段的场景 |
|
||||
| 分步构建 | 细化构建流程 |
|
||||
|
||||
## 方式一：`craft` 一键构建（推荐）
|
||||
|
||||
@@ -90,20 +90,20 @@ spc download "curl,openssl" --with-php=8.4
|
||||
|
||||
```bash
|
||||
# 网络较慢时，可增大并发数和重试次数
|
||||
spc download --for-extensions=bcmath,openssl,curl --parallel 10 --retry=3
|
||||
spc download --for-extensions="bcmath,openssl,curl" --parallel 10 --retry=3
|
||||
|
||||
# 优先使用预编译的二进制依赖，跳过源码编译（大幅加速构建）
|
||||
spc download --for-extensions=bcmath,openssl,curl --prefer-binary
|
||||
spc download --for-extensions="bcmath,openssl,curl" --prefer-binary
|
||||
```
|
||||
|
||||
### 第二步：构建 PHP
|
||||
|
||||
```bash
|
||||
# 构建 cli SAPI
|
||||
spc build:php bcmath,phar,zlib,openssl,curl,fileinfo,tokenizer --build-cli
|
||||
spc build:php "bcmath,phar,zlib,openssl,curl,fileinfo,tokenizer" --build-cli
|
||||
|
||||
# 同时构建多个 SAPI
|
||||
spc build:php bcmath,phar,zlib,openssl,curl --build-cli --build-micro
|
||||
spc build:php "bcmath,phar,zlib,openssl,curl" --build-cli --build-micro
|
||||
```
|
||||
|
||||
|
||||
@@ -125,7 +125,7 @@ spc build:php bcmath,phar,zlib,openssl,curl --build-cli --build-micro
|
||||
硬编译 INI 的例子——预设更大的内存限制，并禁用 `system` 函数：
|
||||
|
||||
```bash
|
||||
spc build:php bcmath,pcntl,posix --build-cli -I "memory_limit=4G" -I "disable_functions=system"
|
||||
spc build:php "bcmath,pcntl,posix" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
|
||||
```
|
||||
|
||||
## 打包 micro 应用
|
||||
@@ -160,7 +160,7 @@ spc micro:combine your-app.phar --output=your-app -N /path/to/custom.ini
|
||||
- `-vvv` 将显示 `DEBUG` 级别的日志，并将其他 shell 命令执行的 STDOUT 输出到终端。
|
||||
|
||||
```bash
|
||||
spc build:php bcmath,openssl --build-cli -vv
|
||||
spc build:php "bcmath,openssl" --build-cli -vv
|
||||
```
|
||||
|
||||
或者，你也可以查看 `log/spc.shell.log` 和 `log/spc.output.log` 获取终端输出和 StaticPHP 日志。
|
||||
@@ -170,7 +170,7 @@ spc build:php bcmath,openssl --build-cli -vv
|
||||
```bash
|
||||
spc reset
|
||||
# 然后重新构建
|
||||
spc build:php bcmath,openssl --build-cli
|
||||
spc build:php "bcmath,openssl" --build-cli
|
||||
```
|
||||
|
||||
::: tip
|
||||
@@ -182,6 +182,7 @@ spc build:php bcmath,openssl --build-cli
|
||||
|
||||
## 接下来
|
||||
|
||||
- [PHP SAPI 构建参考](./sapi-reference) - 各个 PHP 的 SAPI 构建及使用指南
|
||||
- [命令行参考](./cli-reference) — 所有命令与选项的完整说明
|
||||
- [扩展列表](./extensions) — 查看支持的扩展及其依赖关系
|
||||
- [常见问题](./troubleshooting) — 构建失败时的排查指南
|
||||
|
||||
@@ -5,6 +5,8 @@
|
||||
StaticPHP 是一个构建工具，能够将 PHP 解释器与你所需的扩展一起编译成一个独立的二进制文件，无需在目标系统上预先安装 PHP 或任何依赖库。
|
||||
构建产物可以直接分发和运行，适用于 Linux、macOS 和 Windows 平台。
|
||||
|
||||
StaticPHP 的能力不止于 PHP。依托同一套构建基础设施，它还可以将 `curl`、`pkg-config`、`htop` 等常用命令行工具编译为独立的静态二进制，无需在目标机器上安装任何依赖即可直接运行。后续还会持续扩充内置支持的工具集。
|
||||
|
||||
## 为什么要构建静态 PHP
|
||||
|
||||
普通 PHP 安装依赖系统环境：你需要先安装 PHP、再装扩展、再处理各个发行版之间的差异。
|
||||
@@ -18,7 +20,7 @@ StaticPHP 是一个构建工具，能够将 PHP 解释器与你所需的扩展
|
||||
|
||||
## phpmicro：把 PHP 和你的代码打包成一个文件
|
||||
|
||||
[phpmicro](https://github.com/easysoft/phpmicro) 是一个第三方 PHP SAPI，StaticPHP 对其提供原生支持。
|
||||
[phpmicro](https://micro.static-php.dev) 是一个第三方 PHP SAPI，StaticPHP 对其提供原生支持。
|
||||
它能将 PHP 解释器本身和你的 `.php` 源文件（或 `.phar` 打包文件）合并成单个自解压可执行文件（`sfx`）。
|
||||
|
||||
```
|
||||
@@ -48,6 +50,6 @@ StaticPHP 支持将 FrankenPHP 连同所需扩展一起静态编译，
|
||||
|
||||
## 接下来
|
||||
|
||||
- [安装 SPC](./installation) — 安装 StaticPHP 构建工具
|
||||
- [安装 StaticPHP](./installation) — 安装 StaticPHP 构建工具
|
||||
- [第一次构建](./first-build) — 完整流程演示：从下载源码到得到可执行文件
|
||||
- [命令行参考](./cli-reference) — 所有命令与选项速查
|
||||
|
||||
277
docs/zh/guide/sapi-reference.md
Normal file
277
docs/zh/guide/sapi-reference.md
Normal file
@@ -0,0 +1,277 @@
|
||||
---
|
||||
outline: 'deep'
|
||||
---
|
||||
|
||||
# PHP SAPI 构建参考
|
||||
|
||||
::: tip
|
||||
如果你采用的是 spc 二进制方式安装，请将本章节中的所有 `spc` 替换为 `./spc` 或 `.\spc.exe`。
|
||||
|
||||
如果你采用的是源码安装，请将 `spc` 替换为 `bin/spc`。
|
||||
:::
|
||||
|
||||
本页详细介绍 StaticPHP 支持的各类 PHP SAPI 的构建参数和使用方式。
|
||||
|
||||
## 概览
|
||||
|
||||
| SAPI | 构建参数 | 产物路径（Linux/macOS）| 产物路径（Windows）| 平台支持 |
|
||||
|---|---|---|---|---|
|
||||
| cli | `--build-cli` | `buildroot/bin/php` | `buildroot/bin/php.exe` | Linux、macOS、Windows |
|
||||
| fpm | `--build-fpm` | `buildroot/bin/php-fpm` | — | Linux、macOS |
|
||||
| micro | `--build-micro` | `buildroot/bin/micro.sfx` | `buildroot/bin/micro.sfx` | Linux、macOS、Windows |
|
||||
| embed | `--build-embed` | `buildroot/lib/libphp.a` | `buildroot/lib/php8embed.lib` | Linux、macOS、Windows |
|
||||
| frankenphp | `--build-frankenphp` | `buildroot/bin/frankenphp` | `buildroot/bin/frankenphp.exe` | Linux、macOS、Windows |
|
||||
|
||||
## cli
|
||||
|
||||
`cli` 是标准的 PHP 命令行程序，适用于在终端执行 PHP 脚本、交互式 shell 等场景。
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
spc build:php "bcmath,openssl,curl" --build-cli
|
||||
```
|
||||
|
||||
Windows 下产物为 `buildroot/bin/php.exe`，其他平台为 `buildroot/bin/php`。
|
||||
|
||||
完整选项参见 [build:php — SAPI 选择](./cli-reference#sapi-selection) 和 [build:php — 通用构建选项](./cli-reference#common-build-options)。
|
||||
|
||||
### 使用
|
||||
|
||||
```bash
|
||||
# 查看版本和已加载扩展
|
||||
./buildroot/bin/php -v
|
||||
./buildroot/bin/php -m
|
||||
|
||||
# 执行脚本
|
||||
./buildroot/bin/php your-script.php
|
||||
|
||||
# 交互模式
|
||||
./buildroot/bin/php -a
|
||||
```
|
||||
|
||||
### php.ini 路径
|
||||
|
||||
静态编译的 PHP cli 按以下顺序搜索 `php.ini`：
|
||||
|
||||
1. 命令行参数 `-c /path/to/php.ini` 指定的路径
|
||||
2. `PHP_INI_PATH` 环境变量指定的路径
|
||||
3. 编译时通过 `--with-config-file-path` 指定的目录（默认为 `/usr/local/etc/php`）
|
||||
|
||||
可以通过 `./buildroot/bin/php --ini` 查看 PHP 实际使用的 ini 路径。
|
||||
|
||||
### 硬编码 INI
|
||||
|
||||
使用 `-I` 参数可以在编译时将 INI 配置硬编码到二进制中，无需额外的 `php.ini` 文件：
|
||||
|
||||
```bash
|
||||
spc build:php "bcmath,pcntl" --build-cli -I "memory_limit=4G" -I "disable_functions=system,exec"
|
||||
```
|
||||
|
||||
硬编码 INI 适用于 `cli`、`micro`、`embed` SAPI。
|
||||
|
||||
## fpm
|
||||
|
||||
`fpm`（FastCGI Process Manager）与 Nginx、Apache 等 Web 服务器配合使用，适用于传统的 Web 应用部署场景。
|
||||
|
||||
::: warning
|
||||
`fpm` 不支持 Windows 平台。
|
||||
:::
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
spc build:php "bcmath,openssl,curl,pdo_mysql" --build-fpm
|
||||
```
|
||||
|
||||
产物为 `buildroot/bin/php-fpm`。
|
||||
|
||||
完整选项参见 [build:php — SAPI 选择](./cli-reference#sapi-selection) 和 [build:php — 通用构建选项](./cli-reference#common-build-options)。
|
||||
|
||||
### 使用
|
||||
|
||||
将 `buildroot/bin/php-fpm` 拷贝到服务器，像普通的 `php-fpm` 一样使用：
|
||||
|
||||
```bash
|
||||
# 查看版本
|
||||
./buildroot/bin/php-fpm -v
|
||||
|
||||
# 指定配置文件启动
|
||||
./buildroot/bin/php-fpm -c /path/to/php.ini -y /path/to/php-fpm.conf
|
||||
|
||||
# 测试配置文件
|
||||
./buildroot/bin/php-fpm -t
|
||||
```
|
||||
|
||||
### 与 Nginx 配合使用示例
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
root /var/www/html;
|
||||
index index.php;
|
||||
|
||||
location ~ \.php$ {
|
||||
fastcgi_pass 127.0.0.1:9000;
|
||||
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
|
||||
include fastcgi_params;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`php-fpm.conf` 示例：
|
||||
|
||||
```ini
|
||||
[global]
|
||||
pid = /var/run/php-fpm.pid
|
||||
error_log = /var/log/php-fpm.log
|
||||
|
||||
[www]
|
||||
listen = 127.0.0.1:9000
|
||||
pm = dynamic
|
||||
pm.max_children = 5
|
||||
pm.start_servers = 2
|
||||
pm.min_spare_servers = 1
|
||||
pm.max_spare_servers = 3
|
||||
```
|
||||
|
||||
## micro
|
||||
|
||||
`micro` 是基于 [phpmicro](https://github.com/easysoft/phpmicro) 的自包含可执行文件 SAPI。通过 `spc micro:combine` 命令，可以将 `micro.sfx` 与 PHP 代码合并为一个独立的可执行文件，无需在目标机器上安装 PHP。
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
spc build:php "bcmath,phar,openssl,curl" --build-micro
|
||||
```
|
||||
|
||||
产物为 `buildroot/bin/micro.sfx`。
|
||||
|
||||
完整选项参见 [build:php — SAPI 选择](./cli-reference#sapi-selection)、[build:php — 通用构建选项](./cli-reference#common-build-options) 和 [build:php — micro 专用选项](./cli-reference#micro-options)。
|
||||
|
||||
### 打包应用
|
||||
|
||||
使用 `micro:combine` 命令将 PHP 脚本或 phar 文件打包：
|
||||
|
||||
```bash
|
||||
# 打包 PHP 脚本
|
||||
echo "<?php echo 'Hello, World!' . PHP_EOL;" > hello.php
|
||||
spc micro:combine hello.php --output=hello
|
||||
./hello
|
||||
|
||||
# 打包 phar 文件
|
||||
spc micro:combine your-app.phar --output=your-app
|
||||
./your-app
|
||||
```
|
||||
|
||||
### 注入 INI 配置
|
||||
|
||||
打包时可以通过命令行参数或 ini 文件注入运行时配置：
|
||||
|
||||
```bash
|
||||
# 通过命令行参数注入（-I 是 --with-ini-set 的简写）
|
||||
spc micro:combine your-app.phar --output=your-app -I "memory_limit=512M" -I "curl.cainfo=/etc/ssl/certs/ca-certificates.crt"
|
||||
|
||||
# 通过 ini 文件注入（-N 是 --with-ini-file 的简写）
|
||||
spc micro:combine your-app.phar --output=your-app -N /path/to/custom.ini
|
||||
```
|
||||
|
||||
::: tip
|
||||
`-I` 注入的 INI 是运行时配置，通过在 `micro.sfx` 末尾追加特殊结构实现。这与编译时用 `-I` 硬编码 INI 不同，两者可以共存。
|
||||
:::
|
||||
|
||||
### 伪装为 cli SAPI
|
||||
|
||||
部分框架会检查 `PHP_SAPI` 的值，并限制在非 `cli` 环境下运行。`micro` 的 `PHP_SAPI` 默认值为 `micro`，可通过编译参数让其伪装为 `cli`：
|
||||
|
||||
```bash
|
||||
spc build:php "bcmath,phar" --build-micro --with-micro-fake-cli
|
||||
```
|
||||
|
||||
### 指定自定义 micro.sfx 路径
|
||||
|
||||
```bash
|
||||
spc micro:combine your-app.phar --output=your-app --with-micro=/path/to/your/micro.sfx
|
||||
```
|
||||
|
||||
### 关于 phar 的路径问题
|
||||
|
||||
将应用打包为 phar 后，phar 内部使用相对路径可能与预期不符。请参考[开发者文档 - Phar 目录问题](../develop/structure)了解详情。
|
||||
|
||||
## embed
|
||||
|
||||
`embed` SAPI 将 PHP 编译为静态库（Linux/macOS 下为 `libphp.a`，Windows 下为 `php8embed.lib`），可嵌入到其他 C/C++ 程序中运行 PHP 代码。
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
spc build:php "bcmath,openssl" --build-embed
|
||||
```
|
||||
|
||||
产物：
|
||||
- Linux/macOS：`buildroot/lib/libphp.a`，头文件在 `buildroot/include/`
|
||||
- Windows：`buildroot/lib/php8embed.lib`，头文件在 `buildroot/include/`
|
||||
|
||||
完整选项参见 [build:php — SAPI 选择](./cli-reference#sapi-selection)、[build:php — 通用构建选项](./cli-reference#common-build-options) 和 [build:php — embed 专用选项](./cli-reference#embed-options)。
|
||||
|
||||
::: tip
|
||||
如何将 `libphp.a` / `php8embed.lib` 链接到你自己的项目（包括编译器选择、`dev:shell` 使用方式和完整 C 示例），将在开发者文档中专门介绍。
|
||||
:::
|
||||
|
||||
## frankenphp
|
||||
|
||||
`frankenphp` 是基于 [FrankenPHP](https://github.com/php/frankenphp) 的现代 PHP 应用服务器，内置 Caddy，支持 HTTP/2、HTTP/3、自动 HTTPS 等特性。
|
||||
|
||||
::: tip
|
||||
StaticPHP 构建出的 `frankenphp` 是单个完全自包含的可执行文件。这与 FrankenPHP 官方提供的发行版不同，官方版本为动态链接二进制，需要单独安装 PHP。
|
||||
:::
|
||||
|
||||
::: warning
|
||||
FrankenPHP 必须启用线程安全模式，构建时务必加上 `--enable-zts`。
|
||||
:::
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
spc build:php "bcmath,openssl,curl,pdo_mysql" --build-frankenphp --enable-zts
|
||||
```
|
||||
|
||||
Linux/macOS 下产物为 `buildroot/bin/frankenphp`，Windows 下为 `buildroot/bin/frankenphp.exe`。
|
||||
|
||||
完整选项参见 [build:php — SAPI 选择](./cli-reference#sapi-selection)、[build:php — 通用构建选项](./cli-reference#common-build-options) 和 [build:php — frankenphp 专用选项](./cli-reference#frankenphp-options)。
|
||||
|
||||
### 使用
|
||||
|
||||
```bash
|
||||
# 查看版本
|
||||
./buildroot/bin/frankenphp version
|
||||
|
||||
# 以 PHP 内置服务器模式运行（用于开发调试）
|
||||
./buildroot/bin/frankenphp php-server
|
||||
|
||||
# 运行 Worker 模式
|
||||
./buildroot/bin/frankenphp run --config /path/to/Caddyfile
|
||||
```
|
||||
|
||||
更多用法请参考 [FrankenPHP 官方文档](https://frankenphp.dev/docs/)。
|
||||
|
||||
## 动态扩展加载
|
||||
|
||||
静态 PHP 二进制是否能够通过 `dl()` 在运行时加载扩展，取决于其链接方式。
|
||||
|
||||
**macOS** — 构建产物始终动态链接系统库，支持通过 `dl()` 或 `php.ini` 在运行时加载 `.so` 扩展。
|
||||
|
||||
**Linux** — StaticPHP 默认构建目标为 `native-native-musl`：完全静态链接 musl libc 的二进制。由于运行时不存在动态链接器，`dl()` 被禁用，FFI 扩展无法使用，也无法加载任何外部 `.so` 扩展。
|
||||
|
||||
如需在 Linux 上支持动态扩展加载，请在构建前设置 `SPC_TARGET` 环境变量：
|
||||
|
||||
```bash
|
||||
SPC_TARGET=native-native-gnu.2.17 spc build:php "bcmath,openssl" --build-cli
|
||||
```
|
||||
|
||||
如果你采用的是源码安装，也可以在 `config/env.ini` 中设置 `SPC_TARGET=native-native-gnu.2.17`，将其作为所有构建的默认值。
|
||||
|
||||
这将使用 Zig 工具链构建出一个准静态二进制，动态链接 glibc 2.17，可运行于大多数现代 GNU/Linux 发行版，无需 Docker，也无需额外的交叉编译工具链。该产物支持 `dl()`、FFI 和运行时加载 `.so` 扩展，但无法运行于 Alpine Linux 等基于 musl 的系统。
|
||||
|
||||
**Windows** — Windows 上的 PHP 扩展均以 `.dll` 形式分发，且依赖官方动态构建的 PHP 中附带的 DLL 文件。StaticPHP 构建的静态 PHP 可执行文件不包含这些 DLL，因此 Windows 不支持动态扩展加载，所有扩展必须在构建时静态编译进去。
|
||||
|
||||
@@ -1,5 +1,32 @@
|
||||
# 故障排除
|
||||
|
||||
<!-- TODO: 按类别整理常见构建失败及解决方法。
|
||||
章节：下载问题 / 编译错误 / 扩展冲突 / Windows 专项 / glibc Linux 专项。
|
||||
从 v2 troubleshooting.md 迁移并扩充。 -->
|
||||
使用 StaticPHP 过程中可能会碰到各种各样的故障，这里将讲述如何自行查看错误并反馈 Issue。
|
||||
|
||||
## 下载失败问题
|
||||
|
||||
下载资源问题是 spc 最常见的问题之一。主要是由于 spc 下载资源使用的地址一般均为对应项目的官方网站或 GitHub 等，而这些网站可能偶尔会宕机、屏蔽 IP 地址。
|
||||
在遇到下载失败后，可以多次尝试调用下载命令。
|
||||
|
||||
当下载资源时，你可能最终会看到类似 `curl: (56) The requested URL returned error: 403` 的错误，这通常是由于 GitHub 限制导致的。
|
||||
你可以通过在命令中添加 `-vvv` 来验证，会看到类似 `[DEBU] Running command (no output) : curl -sfSL "https://api.github.com/repos/openssl/openssl/releases"` 的输出。
|
||||
|
||||
要解决这个问题，可以在 GitHub 上 [创建](https://github.com/settings/tokens) 一个个人访问令牌，并将其设置为环境变量 `GITHUB_TOKEN=<XXX>`。
|
||||
|
||||
如果确认地址确实无法正常访问，可以提交 Issue 或 PR 更新地址或下载类型。
|
||||
|
||||
## Doctor 无法修复某些问题
|
||||
|
||||
在绝大部分情况下，doctor 模块都可以对缺失的系统环境进行自动修复和安装，但也存在特殊的环境无法正常使用自动修复功能。
|
||||
|
||||
由于系统限制（例如，Windows 下无法自动安装 Visual Studio 等软件），自动修复功能无法用于某些项目。
|
||||
在遇到无法自动修复功能时，如果遇到 `Some check items can not be fixed` 字样，则表明无法自动修复。
|
||||
请根据终端显示的方法提交 Issue 或自行修复环境。
|
||||
|
||||
## 编译错误
|
||||
|
||||
遇到编译错误时，如果没有开启 `-vvv` 日志，请先开启调试日志，然后确定报错的命令。
|
||||
报错的终端输出对于修复编译错误非常重要。
|
||||
在提交 Issue 时，请上传终端日志的最后报错片段（或整个终端日志输出），并且包含使用的 `spc` 命令和参数。
|
||||
|
||||
如果你是重复构建，请参考 [首次构建 - 调试与重新构建](./first-build#调试与重新构建) 章节。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user