在你自己的 runner 上构建 PHP micro（standalone 工作流）
bin/jumphp export:standalone 和 app:export 会把游戏或应用粘到一个 micro 上：一个静态构建的 PHP（StaticPHP），
带有 JumPHP 所需的扩展。micro 由工作流 .github/workflows/standalone.yml 构建，并作为 release standalone-<key> 发布
（key 是 PHP 版本、扩展列表、StaticPHP 的提交以及 JumPHP 的注册表和补丁的指纹：tools/standalone-key.sh）。因此，只有当这些内容之一
发生变化时，micro 才会被重新构建。本页说明如何在你自己的 runner 上运行该工作流（安装 runner 请见 ci-runner.md），
以及 GitHub 的机器免费提供、而你的机器可能没有的东西。
运行
Forge > 仓库 > Actions > standalone > Run workflow，或在终端中运行（在 JumPHP 项目里，gh 指的是 forge 的那个）：
gh workflow run standalone.yml -f extensions=tools/app-extensions.txt -f macos=false -f linux=false
| 输入 | 取值 | |
|---|---|---|
extensions |
tools/standalone-extensions.txt（游戏：SDL、OpenGL、OpenAL）、tools/app-extensions.txt（桌面应用、IDE）、tools/hybrid-extensions.txt |
构建出的 micro = 它自己的 key |
linux |
true / false |
false：不构建 Linux micro（见下文“Docker”）；此时 export:standalone 会在用户的电脑上构建 Linux 的 micro |
macos |
true / false |
false：不构建 Mac micro（仅桌面应用）；没有 macOS runner 时，这些作业会一直等待下去 |
Windows 作业在下载已缓存的情况下大约需要 10 分钟，第一次需要 30 到 60 分钟。其产物：
https://<forge>/<所有者>/<仓库>/releases/download/standalone-<key>/micro-windows-x86_64.sfx。
GitHub 的机器有、而你的机器可能没有的东西
在 GitHub 上，同一个工作流“自己就能跑”，因为 windows-latest 和 ubuntu-latest 是 GitHub 预先准备好的镜像。
你自己的 runner 是一台裸机。以下各项要么由工作流处理，要么在这里说明：
| GitHub 的镜像 | 你自己的 runner | 工作流做什么 / 你要做什么 |
|---|---|---|
PowerShell 7（pwsh）、PHP、Composer、Git |
通常只有 Windows PowerShell 5.1 和 Git | 各步骤在 Windows PowerShell 中运行；缺少 PHP 8.4 和 Composer 时会下载（php.net、getcomposer.org，校验指纹）；Git 的 usr\bin 会加入 PATH |
| 英文版 Windows | 你的 Windows 的语言（法语……） | VSLANG=1033 让 Visual Studio 的工具输出英文：PHP 的 configure.js 会读取链接器的输出，否则会因 JScript 错误而停止 |
| Visual Studio 2022 | 需要你自己安装：Build Tools 2022，“使用 C++ 的桌面开发”工作负载 | Windows runner 唯一必须具备的东西（另加 Git for Windows）。install-windows-runner.ps1 会安装这两样 |
快速访问 api.github.com，很少受限 |
同一个 API 返回 504 或 “rate limit exceeded” |
StaticPHP 的下载会重试 4 次，并在两次运行之间保存在 %USERPROFILE%\.spc-downloads 中；Composer 从源码安装（--prefer-source） |
actions/upload-artifact@v4、download-artifact@v4 |
Forgejo 不支持它们（“not currently supported on GHES”） | 在 forge 上，Windows 作业自己把 micro 发布到 release（作业的 github.token，forge 的 API）；release 作业只在 GitHub 上运行 |
| Linux 作业中的 Docker | 作业运行在没有 Docker 的容器里 | 见下文 |
| LF 换行 | Git for Windows 会转换为 CRLF | 克隆 StaticPHP 之前运行 git config --global core.autocrlf false（对其文件的补丁依赖于它们的文本） |
Docker：哪里需要，哪里不需要
- Windows 作业使用 Visual Studio 原生编译。它不使用 Docker，而 Windows runner 也做不到（Windows 下的 Linux 容器要通过 WSL2）。为此无需安装任何东西。
- Linux 作业会运行
docker build docker/standalone，然后运行 StaticPHP 的docker run。在作业容器里没有 Docker，除非 runner 提供了一个：把宿主机（或 runner 的 dind）的 Docker socket 挂载到作业中（runner 的config.yml里的container.options/valid_volumes），或者使用 WSL2 Linux runner（ci-runner.md 第 4 节）， 即带 Docker 的真正的 Linux。否则请用linux=false运行：bin/jumphp export:standalone <id> --linux会在执行导出的电脑上构建 Linux micro （大约 15 分钟，之后保存在~/.jumphp/standalone/中）。 - 无论使用哪种 runner，都绝不要把 micro 复制或重命名到另一个 key 下：那会得到一个没有正确扩展的 PHP，
用户的可执行文件会崩溃（
Call to undefined function SDL_Init()）。如果 key 变了，就必须重新构建 micro。
故障排查
作业日志要在 forge 中该次运行的页面上查看（作业 > 红色的步骤）；forge 的 API 不会返回它们。
| 症状 | 原因 / 解决办法 |
|---|---|
key 作业在 30 秒内失败，就在 “Fetching the repository” 之后 |
作业容器无法解析 forge 的名称：runner 的 Docker-in-Docker 没有通往外部的 DNS。给它配上：在 runner 的 compose 文件中为 dind 服务设置 dns: [1.1.1.1, 9.9.9.9]。测试：docker run --network <一个新网络> node:20-bookworm getent hosts <forge> |
Cannot find: pwsh in PATH |
工作流要求使用 Windows PowerShell（shell: powershell）；旧的副本要求 pwsh。请更新它 |
在 “Checking for link.exe” 之后出现 configure.js ... Erreur d'exécution Microsoft JScript |
Visual Studio 的工具以 Windows 的语言输出。使用 VSLANG=1033（本页之后的工作流中已包含） |
ERROR: bison is required |
在同一文件夹中构建到一半之后出现：StaticPHP 保留了 msys2 工具，但没有把它们放回 PATH。删除工作区中的 spc/pkgroot、spc/source、spc/buildroot 后重新运行（干净的工作区，比如新作业的，是可以的） |
| StaticPHP 的补丁 “not patched (StaticPHP changed)” 或 “Failed patch module” | CRLF 换行（设置 core.autocrlf false 并重新克隆），或者源码文件夹已被之前的尝试打过补丁（删除 spc/source/php-src） |
Failed to get GitHub release API info for madler/zlib / HTTP/2 504 |
api.github.com 对你的地址进行限流或出错。工作流会重试；在新机器上的第一次运行可能需要再试一次。下载内容会被保留：每次尝试都会走得更远 |
GHESNotSupportedError: upload-artifact@v4 ... not currently supported |
你在使用 Forgejo：请使用本仓库的工作流（它不用 artifact 就能发布） |
| macOS 作业一直处于 “waiting”，运行永远不会结束 | 没有 macOS runner：使用 -f macos=false |
Cannot find path ...\buildroot\bin\micro.sfx |
之前构建已经失败：请看上面的几行（它们才是原因） |
给 AI 代理
有人可能会要求你“让 standalone 工作流在我的 runner 上跑起来”。请阅读该次运行页面上失败的步骤（如果你无法访问，请让
用户粘贴出来），修改工作流（它必须在 GitHub 上仍然有效：测试
github.server_url），而不是用户的机器，除非缺少的是上面的某个前提条件（Git、Visual Studio Build Tools、
Linux 作业所需的 Docker）：这时请告诉用户，并且只有在用户同意后才安装。绝不要注册 runner，绝不要把令牌
写入文件，绝不要发布不是用该工作流的命令基于当前文件构建出来的 micro，绝不要把 release 移到另一个 key 下。成功运行之后，请检查该文件
（gh release view standalone-<key>，下载返回 200），对于 Windows 的 micro，还要在 runner 的机器上用它运行一个脚本
（copy /b micro.sfx + test.php test.exe，然后 test.exe：PHP 版本、extension_loaded('ffi')……）。