Build from source

从源码制作安装包

本页供开发者制作和验证工具包；默认分支也仍在开发中，不推荐把源码入口当成已验证的故障解决办法。

获取源码后只启动一个文件。它会自动准备锁定材料、制作并校验安装包，再让你确认安装、选择项目，自动构建和验证。无需复制长段下载、摘要校验或打包命令。

获取源码

在已安装 Git 的终端取得开发源码，记下实际提交用于复现问题：

git clone --depth 1 https://github.com/supdger/webman-aot-builder.git webman-aot-builder-source
cd webman-aot-builder-source
git rev-parse HEAD

Receiving objects ... done 和 Resolving deltas ... done 表示 Git 已下载源码；git rev-parse HEAD 输出是问题复现所需的源码身份。命令失败或出现 fatal: 时先处理错误。入口在含 build.command 和 build.cmd 的源码根目录。

macOS Apple Silicon（macOS 终端）

在源码根目录执行一次：

sh ./build.command

入口会准备锁定 PHP 材料，显示下载状态和 SHA-256 检查结果，再让你选择轻量包、完整包或取消。准备材料时的 [成功] 表示该阶段完成；后续菜单会直接显示，不必自己判断下一条命令。选包后自动制作安装包、检查包清单并在隔离目录确认版本。

Windows x64（PowerShell / CMD）

在源码根目录的 PowerShell 执行一次：

.\build.cmd

CMD 中执行 build.cmd 即可。入口自动准备 Windows 运行环境、下载锁定材料、显示进度并提供相同菜单，不需要先手工安装 PHP。

构包完成后的选择

看到 “安装包已就绪：…”、大小和 “校验：包清单和隔离安装版本均通过” 表示源码构包成功。入口随即显示安装目标和 PATH 影响，询问 “是否安装？1 安装；0 取消”；选择安装后自动完成安装与新版本检查。取消时安装包留在显示的输出目录，不会执行安装。

安装成功后选择 1 构建项目，输入已完成 Composer 依赖安装的 Webman / SaiAdmin 项目根目录。工具自动依次构建并验证。看到 “项目构建与校验成功” 与 dist-aot/ 路径表示本机流程完成。项目失败可以重试、重选目录或结束；无需另外执行校验命令。完整安装流程见 安装入口，错误处理见常见问题。

项目构建会忽略任意目录层级中精确名称为 .DS_Store 的文件；这是后续 Webman / SaiAdmin 项目构建的源码快照与隔离镜像规则。真实源码或依赖变化仍会中止构建；按列出的相对路径检查，待依赖安装或编辑写入结束后再重试。

本机验证检查构建产物结构、完整性及工具报告的静态属性；部署后仍需按 Linux 目标机验收 检查启动、数据库和业务接口。

0.4.0 项目续编与全量重建

本节适用于正式 0.4.0 程序及配套工具链。旧 0.3.2 安装和 Composer 0.3.7 绑定的旧运行时没有此功能；从开发源码制作工具包时，须确认程序、编译器补丁和对应组件来自同一候选或正式发行，不能用旧组件代替。正式资产以 v0.4.0 Release 及其中 SHA256SUMS 为准。

在已准备好 Composer 依赖的 Webman / SaiAdmin 后端根目录运行：

webman-aot build

默认检查已完成单元的输入标识、对象大小与 SHA-256，符合条件的对象才复用。未完成或损坏的单元从头编译，不能继续半个正在编译的文件。源码、头文件、编译参数、PHP ABI、实际工具链与 SDK 内容、配置或编译器补丁发生变化时，受影响的旧对象不复用。

项目失败后先查看原始错误与日志、修正原因，再运行相同命令。引导菜单的 1 继续编译同一项目，2 重选目录，3 全量重建此目录，0 结束。需要全部单元重编时运行：

webman-aot build --fresh

对象缓存位于项目内 .webman-aot-builder/cache/objects/，每轮使用独立 .webman-aot-builder/build/attempt-* 目录。失败目录和缓存会保留并占用磁盘；成功后只清理本轮 attempt。--fresh 跳过对象复用，但不清理旧缓存、旧失败 attempt。不要在编译进程仍运行时手动清理工作目录。

即使全部对象都可复用，每轮仍重新链接，核对当前项目输入与完整覆盖，并验证最终产物。以本轮构建及自动校验成功、显示 dist-aot/ 为准；后续仍须在 Linux 检查启动和业务。现有平台证据见测试与验证范围。

维护者制作独立 setup

tools/package-setup.php 从实际已核验的同平台轻量、完整安装包生成固定 HTTPS 下载地址、大小及 SHA-256 的入口。macOS 生成保留执行权限的 setup ZIP，Windows 生成 setup CMD。生成器只产生本机文件；发布前必须核对正式资产身份和下载地址，并在对应平台验证下载、安装、项目构建与验证。

构包、安装及业务验收是不同结果；已有证据与未闭合范围见测试与验证范围。

v0.3.2 实机测试记录

2026-09-30，用户提供了 macOS Apple Silicon 实机安装、构建 SaiAdmin 项目以及 Linux x86_64 服务器启动的终端记录。此次使用 v0.3.2 正式轻量安装包，从包内 install.command 安装并选择构建项目；不是从源码制作安装包的测试。以下仅摘录关键节点，省略重复的文件清单、逐文件编译输出及等待状态；用户名、主机名和本机绝对目录不公开，产物路径统一标记为 <项目目录>/dist-aot。

Mac 实机：安装、准备工具链与构建

阶段	本次终端记录结果
安装与版本确认	包内 SHA-256 校验通过；安装耗时 0.8 秒、退出码 0；版本为 webman-aot 0.3.2。
下载并准备锁定组件	下载 260,125,613 字节，23 秒到达 100%；解包并校验 7614/7614 条目，工具链启用成功。
编译	2063/2063 个编译单元完成，编译进程耗时 529.8 秒、退出码 0。
构建与打包	总耗时 582.3 秒、退出码 0；生成 dist-aot/。
产物校验	耗时 0.8 秒、退出码 0；检查本机构建产物结构和完整性及工具报告的目标静态属性。

原始关键节点摘录；最后的产物路径仅做脱敏替换：

Package contents SHA-256 verified.
[成功] 校验包并安装，耗时 0.8 秒，退出码 0
webman-aot 0.3.2
[prepare] 260125613 / 260125613 bytes (100.0%); 9.79 MiB/s; preparation elapsed 23s
[prepare] Extracted 7614/7614 verified entries
[prepare] Minimal component SHA-256 verification complete
[prepare] Minimal toolchain activated and ready.
[2063/2063] 100% extension-webman_server.cc
Successfully compiled 2063 files
[build] Compiler process completed in 529.8s; exit code 0.
[成功] 构建项目，耗时 582.3 秒，退出码 0
[成功] 校验本次项目产物，耗时 0.8 秒，退出码 0
实际校验范围：本机构建产物结构和完整性
项目构建与校验成功。
产物位置：<项目目录>/dist-aot

构建日志报告的 server SHA-256 为 7dc3c84ef3cab67d229aab4a379fa9b8609b5e0c1b6bad1735d0aeca0f213707。这标识 Mac 构建结果；下方服务器启动记录没有附带服务器端 SHA-256 输出，因此尚未以服务器端摘要复核部署文件身份。

Linux 实机：服务启动

用户将产物部署到 Linux x86_64 服务器，在产物目录执行 ./start.sh。原有 8787 端口已被其他 PHP 服务占用；调整外置配置后，本次实际监听的是 0.0.0.0:8788。

以下摘录启动结果；进程用户名替换为 <用户>，其他版本、监听地址、worker 数和状态保留原记录：

Workerman[main.php] start in DEBUG mode
Workerman/5.2.2         PHP/8.4.25 (JIT off)          Linux/5.10.134-16.3.al8.x86_64
event-loop  proto       user        worker      listen                 count       state
select      tcp         <用户>      webman      http://0.0.0.0:8788    8            [OK]
Press Ctrl+C to stop. Start success.

此记录证明程序在该 Linux 服务器执行、进入 Workerman 启动流程并报告 8 个 worker 启动成功。目前结论是 Linux 启动通过，还没有 HTTP 请求响应、数据库连接、登录或其他业务接口的验收记录。原日志同时包含 Carbon / ThinkPHP 返回类型、Brick 抽象静态方法和 Finder callable 的 Deprecated / Warning；这些告警没有阻止本次启动，但尚未完成影响核查，不能将本次结果描述为“无告警”或“业务全部通过”。继续验证按 Linux 目标机验收 执行。

构包维护与复现

构包锁定的输入来自 toolchain.lock.json、toolchain/minimal-components.lock.json 和 installer/runtime.lock.json。tools/package-installers.php 制作工具包，tools/package-setup.php 制作指向实际资产的 setup；入口统一驱动这些步骤。组件锁升级需要同时核对上游身份、源资产大小与摘要、许可证及两种包的实际内容；不能只换下载地址。

自己制作的外层 ZIP / tar.gz 不保证与公开包逐字节相同。包内清单用于核对本包 payload；不要用公开归档的外层摘要判定自制包内容。对照时先明确输入与修订，逐文件比较内容，再测试私有安装与项目构建。构包输出、安装目录和业务项目目录是三个不同位置。

取消安装时构包产物保留在入口显示的输出目录；验证另一个包使用独立解压与安装目录，不覆盖上一份。历史手工打包命令和资产身份可以从 Wiki 的 Git 历史与发布记录追溯，不将过时命令复制为当前推荐步骤。

SDK 来源与维护者重建

普通源码构包入口仍是开发机上的 build.command 或 build.cmd。组件中包含项目自建补丁 SDK；它以锁定官方 TypePHP / PHPX 源码与原始 SDK 为输入重建 PHPX 静态运行库，不能把原始官方 SDK 当成同一产物。补丁 SDK 面向 Linux x86_64 musl 目标，开发机平台仍为 macOS Apple Silicon 或 Windows x64。普通安装用户继续使用 setup，无需单独下载 SDK 素材。

SDK 原始输入、源码引用与补丁、实际编译命令、构建工具身份、库和头文件摘要记录在 builder-derivation.json；源锁、组件清单与 SDK 指纹共同约束使用的字节。摘要漂移会拒绝准备或编译，不能手动改摘要绕过检查。最终补丁 SDK 使用本仓库独立发行资产，不能把官方 URL 换成新摘要。

tools/rebuild-phpx-sdk.php 是维护者 producer，与安装器分开。生产实现使用 macOS 的 /usr/bin/tar、/usr/bin/unzip，不能直接把这一命令当成 Windows producer。所有参数按 --name=value 形式给出；准备好下列真实输入后才能执行，脚本不会自动猜路径：

参数	输入或输出
--typephp	按补丁清单校验的 TypePHP 0.9.2 源码目录，含锁定 PHPX 源码。
--upstream-sdk-archive	源锁记录的原始官方 SDK 归档，不是补丁 SDK。
--typephp-archive、--phpx-archive	源锁指定的完整官方源码归档；生产流程从完整原始树起步，仅允许补丁清单批准的修改。
--sysroot、--sysroot-component-archive	来源锁中 evidence.patchedSdk.sysrootInput 指定的前序 macOS 组件归档及从中取得的 sysroot；逐项校验文件和链接。不要用当前组件代替前序生产输入。
--clang、--cmake、--ar、--ranlib、--objcopy	真实工具文件路径，结果记录版本及二进制摘要。clang 同目录须存在追加 ++ 后缀的 C++ 编译器；两者均校验为前序锁指定字节。C++ 的目标、sysroot 和标准库搜索路径由生产脚本配置。
--output	尚不存在的新私有输出目录；已有目录会拒绝覆盖。
--archive-root	形如 webman-aot-builder-0.3.2-derived-linux-x86_64-sdk 的产物根名称。

生产脚本显示输入校验、实际构建输出、存活状态及最终 SDK 指纹，失败时保留非零退出。输出目录包含 SDK 树及 result.json。当前脚本不直接生成发行 tar.xz；后续归档、回填锁与双端组件构包必须依据真实生产收据完成。当前已生成 webman-aot-builder-0.3.2-derived-linux-x86_64-sdk.tar.xz，源锁的 phpx-sdk-linux-x64.sourceUrl 指向同仓库 v0.3.2 的该资产；归档 SHA-256 为 6672f8cfa62d8e55308cb5008b625e68ecd9cc93ba000731fbba0838d0c5ffed。源锁 SHA-256 为 79fce2da1dafe1184228130a8aa6c9eda16d72bdd51e05cb40630c8ae7836399。上述摘要标识具体生产输入；公开资产与正式发布状态以 v0.3.2 Release 为准。