Install

安装入口

当前安装流程用于开发验证，已知使用问题见开发状态。根据开发机选择macOS Apple Silicon 安装或Windows x64 安装。两平台均构建 Linux amd64 产物。

安装引导可直接构建一个项目。以后独立构建时，使用Webman 指南或SaiAdmin 指南。安装位置、升级和卸载见升级与卸载。

发布记录与历史验证边界见开发状态与历史记录。本页保留原 Install 地址。

选择一种开始方式

只安装工具时可以暂不准备或选择项目。要构建时，先为目标项目运行 composer install 并准备 vendor/，再选择包含 composer.json、composer.lock、start.php、app/ 的后端根目录；构建和本机校验成功后显示 dist-aot/ 位置。

• 方式一：Composer：开发机有 PHP 8.1+、Composer 2.5.3+；按本页下方命令安装 supdger/webman-aot-builder，首次信任后自动识别系统、准备运行时，再选择项目。
• 方式二：安装包：从最新 Release取得对应开发机 setup。按本页“方式二”解压并运行对应系统的入口，选轻量/完整包、确认安装。
• 方式三：源码编译：同样的开发机；锁定材料需联网；从最新正式版下载 Source code (zip) 后解压，进入含 build.command、build.cmd 的源码根目录。Mac 运行 sh ./build.command，Windows PowerShell 运行 .\build.cmd；构包校验后确认安装并选择项目。详见源码构建指南。

方式一：Composer

包名为 supdger/webman-aot-builder。请使用当前正式入口；入口按自身校验清单准备对应的完整运行时。开发机需系统 PHP 8.1+、Composer 2.5.3+，以及 macOS curl/tar 或 Windows curl.exe/PowerShell 5.1。PHP 8.4/Composer 2.9.5/macOS 已验证；配套原生运行时的 Windows CI 安装与续编已通过，详见验证记录。PHP 8.1 和 Windows 真机续编仍未验收。

在 macOS 终端或 Windows PowerShell 运行同一条安装命令：

composer global require "supdger/webman-aot-builder:*"

首次 Composer 询问是否信任 supdger/webman-aot-builder 插件时输入 y。这是 Composer 自己的信任确认；包安装与自动加载完成后，程序自动识别系统并打开资源菜单，随后进入已有项目流程。重复运行这条普通安装命令也会打开菜单，已保存信任后不重复询问。

若选择 n 或 d，仅安装普通入口，之后可以用下方命令主动启动。非交互、CI、--no-plugins、--no-scripts、--dry-run、--no-update、--no-install 不自动启动；其他包、局部项目和其他 Composer 命令也不会自动打开菜单。

0.4.5 入口在父 Composer 的命令事件中，仅对已启用插件的全局 exec 且 binary 精确为 webman-aot 关闭本次进程超时；不会修改全局配置或放宽其他命令。macOS 上已用父 1 秒计时、菜单等待 2 秒验证正反例，不能据此声称 Windows 物理终端已验收。旧入口、禁用插件或缺少该事件能力时，继续使用下方直接 PHP 代理。

终端正常等待没有交互截止时间；正常 EOF 安全结束。真实读取错误会显示终端断开及恢复入口，失败退出。macOS 恢复控制台仍监测父入口，短周期仅用于探测故障，正常无数据与半行继续等待，完整行或 EOF 才交给菜单。

已安装者，或下次使用时，直接启动 PHP 代理：

macOS 终端：

php "$(composer global config bin-dir --absolute)/webman-aot" guide

Windows PowerShell：

$aotBin = (composer global config bin-dir --absolute).Trim()
if ($LASTEXITCODE -ne 0) { throw '无法读取 Composer 命令目录。' }
php (Join-Path $aotBin 'webman-aot') guide

命令自动取得代理路径，无需区分资源架构或修改 PATH；已配置 Composer 命令目录的终端也可直接运行 webman-aot。菜单可选开始、导入完整包或结束；开始会复用已就绪资源，首次显示真实下载、校验和安装进度，准备成功后直接进入项目菜单。升级会先校验已下载的完整包；发行包支持轻量升级且旧组件校验通过时，可只取得程序和必要替换文件。无法复用时会显示原因，再取得完整包，详见升级与卸载。

直接 PHP 入口不受 composer global exec 默认 300 秒子进程超时限制，适合下载完整包及长时间交互；无需修改 Composer 全局超时。

下载中断、超时或按 Ctrl+C 取消后，未完成内容保存在私有状态目录的 cache/*.part。macOS 的引导父入口被 Composer 超时终止时，也会停止本次下载并保留进度；用上面的直接 PHP 入口重试。再次运行上面的命令并选择开始，会显示已有字节数并继续下载；单次流程最多自动重试 2 次，每次也从已有位置继续。下载没有固定总时长截止，连接超过 20 秒或连续 120 秒几乎没有数据才超时。已下载完成的 .part 也会先校验，通过后直接使用，无需重新下载。完整包通过大小和 SHA-256 校验后才解包，损坏内容会清除；服务器拒绝续传时会明确提示并从头下载。下载失败后仍可选择导入本地完整包。

需要升级 Composer 入口或恢复缺失入口时，使用升级与卸载中的固定升级命令，成功后再运行引导。日常继续构建可直接运行上面的引导命令。部分下载只有仍保留在缓存且与当前入口所需资源相符时才能复用；已经删除的内容无法恢复。

输入或拖入已完成 composer install 的 Webman 项目完整路径，须包含 composer.json、composer.lock、start.php 和 app/。构建后自动校验并显示 dist-aot/；失败保留本机日志和原退出码，可重试或重选。项目流程结束会单独说明结果和退出码，Composer 包安装已完成，后续安全审计照常执行。菜单本机校验不代表 Linux 部署或数据库、登录等业务验收。

网络失败会显示当前入口所需的完整包文件名与下载链接，可在同一流程输入/拖入完整路径，或回车检查常规 Downloads。按入口提示从最新正式版取得匹配的完整包；程序自动选择当前开发机，导入时验证大小、SHA-256、版本和平台。不要复用旧教程的文件名或旧安装包；components.zip 不是完整安装包。

私有目录为 macOS ~/Library/Application Support/webman-aot-composer 或 Windows %LOCALAPPDATA%/webman-aot-composer，不会覆盖旧安装或修改 PATH；已有无本入口所有权的目录拒绝接管。非终端无参不交互、不下载、不写状态。显式 guide 只在打开真实连接的控制台后恢复交互；--non-interactive、COMPOSER_NO_INTERACTION=1、CI=1 禁止恢复。

需要自定义构建参数时，在项目目录使用 webman-aot build；SaiAdmin 使用 --profile=saiadmin，或通过官方 composer global exec -- webman-aot build --profile=saiadmin。自动化环境可先准备：

webman-aot setup --yes --non-interactive
# 或导入已下载完整包
webman-aot setup --archive="/完整安装包路径" --non-interactive

隔离目录使用 --state-dir="目录"，guide/setup 的选项可放在命令后；doctor/build 的全局选项须前置。版本查询不联网，只说明入口与目标运行时，不代表资源已就绪。核对当前入口输出与最新正式版的发布说明，运行时资产和校验清单使用同一发行版提供的材料；不能用旧版本包替代。

方式二：原生安装包

这种方式不需要 Composer 全局安装工具。开发机需为 macOS Apple Silicon 或 Windows x64；先按支持平台核对系统条件。setup 需要联网取得所选安装包，安装包自带私有 PHP。自己的 Webman 项目仍需预先完成 composer install；只安装工具时可以暂不选择项目。

下载并启动

打开最新正式版，按开发机下载下表中的 setup。放到一个新目录，该目录只保留一个对应平台的 setup，避免通配符选中多个文件。

开发机	下载文件的名称后缀	在哪里运行
macOS Apple Silicon	-macos-arm64-setup.zip	macOS 终端
Windows x64	-windows-x86_64-setup.cmd	Windows PowerShell

macOS：终端进入刚才的下载目录，解压并启动；文件名由通配符匹配，无需手工改版本：

unzip webman-aot-builder-*-macos-arm64-setup.zip
bash ./webman-aot-builder-*-macos-arm64-setup.command

Windows：PowerShell 进入刚才的下载目录，运行：

$setup = Get-ChildItem -File .\webman-aot-builder-*-windows-x86_64-setup.cmd
if (@($setup).Count -ne 1) { throw '此目录必须只有一个 Windows setup CMD，请检查下载文件。' }
& $setup.FullName

选择资源并确认安装

1. 选 1 轻量包 或 2 完整包；0 取消结束流程。轻量包首次构建需要联网准备组件；完整包已包含组件，取得安装包后可离线准备工具资源。项目依赖不包含在工具包内。
2. 等待下载、大小与 SHA-256 校验及归档检查。看到“包检查成功，进入安装确认与项目下一步”后继续；失败时按显示的错误处理，不跳过校验。
3. 核对显示的安装目录、启动命令位置和 PATH 影响，再确认安装。看到“安装成功，当前入口可以直接构建项目”表示工具安装完成，记下显示的启动命令位置。
4. 若立即构建，选 1 构建项目，输入或拖入已准备好的 Webman 后端根目录（含 composer.json、composer.lock、start.php、app/）；选 0 结束则只保留工具安装。

核对入口与下一步

重新打开终端。先检查短命令实际指向哪里，再查询版本；路径应对应上一步安装器显示的启动命令，版本应对应所选正式包。

macOS：

command -v webman-aot
webman-aot version

Windows PowerShell：

Get-Command webman-aot -CommandType Application | Select-Object -ExpandProperty Source
webman-aot version

若找不到命令或指向另一套安装，先用安装器显示的启动命令完整路径查询版本，并按常见问题检查 PATH；不要把另一套入口的输出当作本次安装结果。

以后进入自己的项目根目录运行 webman-aot build，SaiAdmin 项目加 --profile=saiadmin；按Webman 构建或SaiAdmin 构建继续。看到“项目构建与校验成功”及 dist-aot/ 路径后，再按部署到 Linux检查目标环境与业务。只查询版本不表示项目已构建或验收。

升级或清理安装使用升级与卸载，查询和清理都可使用当前正式版独立入口。平台补充步骤与故障处理见macOS 安装和Windows 安装。

安装包文件怎么选

文件名中 macos-arm64 / windows-x86_64 表示开发机；最终产物目标为 Linux amd64。第一次安装优先选 setup，运行后按菜单选轻量包或完整包、确认安装，再输入已完成 Composer 依赖安装的项目根目录。

文件名后缀或资产	用途
macos-arm64-setup.zip	macOS Apple Silicon 推荐入口；解压运行 .command。
windows-x86_64-setup.cmd	Windows x64 推荐入口；运行 .cmd。
不含 full 的平台安装包	轻量包；首次准备编译组件需要联网。
含 full 的平台安装包	完整包，内置编译组件；项目 Composer 依赖与构建文件须预先准备，不等于业务完全离线。
components.zip	工具自动获取的编译组件，不能独立安装工具。
derived-linux-x86_64-sdk.tar.xz	本项目重建的 Linux 目标 SDK，供维护者源码重建；普通用户不用单独下载。
SHA256SUMS	当前发行版下载资产的校验清单；setup 自动校验所选安装包。
GitHub Source code	工具源码，直接安装请选择 setup 或安装包。

以上文件从最新正式版获取，文件名中的版本以该页资产为准；使用同一发行版的校验清单。历史变更见更新日志。

macOS 首次双击被系统拦截

首次双击 setup.command 或 install.command，可能看到“未打开”或“Apple 无法验证”提示。先确认文件来自本项目 正式发行页，并用同一版本的 SHA256SUMS 核对下载文件，然后按以下步骤操作：

1. 在提示窗口点 “完成”，保留文件，不要点“移到废纸篓”。

   

2. 打开苹果菜单 → 系统设置 → 隐私与安全性，向下滚动到 “安全性”。

3. 找到“已阻止 install.command（或 setup.command）”的提示，确认文件名后点 “仍要打开”。

   

4. 按系统提示再次确认“打开”或“仍要打开”，并完成登录密码或 Touch ID 验证。若终端未自动出现，回到解压目录，再双击同一个 .command。

5. 终端打开后，按安装器提示继续。

若找不到“仍要打开”，重新双击一次文件，再回到该设置页面；该按钮通常只在尝试打开后约一小时内显示。详见 Apple 官方说明。以上步骤适用于“无法验证”提示；若提示“将损坏你的电脑”或“文件已损坏”，请停止安装，重新下载并核对校验值。

方式三：从源码制作安装包

适合需要自行构建工具的开发者。普通使用者可选择上面的 Composer 或原生安装包方式。

从最新正式版下载 Source code (zip)，完整解压，进入含 build.command、build.cmd 的工具源码根目录。按源码构建指南准备该平台所需环境及锁定材料；首次获取材料需要联网。

macOS 终端：

sh ./build.command

Windows PowerShell：

.\build.cmd

构包校验成功后，入口会询问是否安装。确认安装并选择项目后，按上方“核对入口与下一步”检查启动命令、版本和构建结果；源码编译失败时先处理显示的阶段与错误，不运行未通过校验的包。

项目失败后继续编译

项目需先准备 Composer 依赖及 vendor/，选择含 composer.json、composer.lock、start.php 和 app/ 的后端根目录。构建失败时先处理显示的错误，之后选择 1 继续编译；已完成且输入与完整性校验通过的单元会复用，其余单元从头编译。选择 2 可重选目录，3 全量重建此目录，0 结束。Composer 安装者下次可运行 composer global exec -- webman-aot guide；原生安装或源码构包安装者从项目根目录运行 webman-aot build，具体步骤见Webman 构建或SaiAdmin 构建。

需要单独执行时，在项目根目录运行 webman-aot build，SaiAdmin 可加 --profile=saiadmin；webman-aot build --fresh 会重新编译全部单元。--fresh 保留旧缓存和失败目录，不释放磁盘空间。每次仍重新链接并校验产物，以本轮构建与自动校验成功、显示 dist-aot/ 为完成依据。缓存、输入变化及磁盘影响见源码构建指南，平台边界见测试与验证范围。

构建会显示阶段及编译器的实际文件计数。持续无输出时显示存活状态、已用时间和无输出时长，工作进度仍未知，不能推断卡死或预计完成时间。成功时显示 dist-aot/ 位置；失败保留原始错误、耗时、退出码和本机日志位置，可重试、重选项目或结束。本机校验不能代替 Linux 的启动、数据库与业务验收。

需要先清理多个历史版本再使用 Composer 时，按升级与卸载先查询、再从已核对的 PHP 入口逐项确认旧原生项，保留 Composer 全局包。无需先安装或更新工具；入口缺失时可直接使用独立解压的源码。清理使用当前正式版的卸载入口，不能假定旧安装目录中存在可用脚本。