Webman TypePHP AOT 构建插件

适配：workerman/webman-framework:dev-master，稳定版等待官方后续发布

✨ 简介

tinywan/webman-typephp 是面向 Webman 2.x 的 TypePHP AOT 构建插件。基于现有 Webman 项目自动生成 AOT 入口文件与 Linux 编译配置，调用 Docker 构建镜像完成 AOT 预编译，最终输出一套可直接部署到 Linux 服务器的便携 dist/ 产物。

开发机环境要求：仅需 PHP、Composer、Docker，无需手动安装 C++、Clang、TypePHP 编译工具链，全部编译动作在容器内完成。

🚀 快速上手

1. 安装插件（开发依赖）

composer require tinywan/webman-typephp --dev

2. 环境预检

检查 PHP、Docker 服务是否就绪，一键诊断：

php webman typephp:doctor

输出示例：

=== TypePHP Environment Diagnostic Tool ===
• PHP Version: 8.5.10 [OK]
• Docker: Docker version 29.7.2, build a7dcaa6 [OK - Required for Phase 1]
• Host Clang Compiler: Not installed [OK - Handled inside Docker builder]

宿主机不用装 Clang，编译全部交给 Docker builder。

3. 编译打包

# 默认输出到 dist/
php webman typephp:package

# dist/ 已存在时，显式确认覆盖
php webman typephp:package --force

# 强制使用最新 TypePHP stub 重置 main.php 入口（原有 main.php 会自动备份为 main.php.bak）
php webman typephp:package --refresh-main

# 构建全静态单文件可执行产物 (零动态库依赖，单二进制)
php webman typephp:package --static

默认构建镜像：tinywan/typephp-webman-builder:v0.0.17

4. 服务器部署 & 启动

把打包完成的 dist/ 目录上传到 Linux x86_64/glibc 服务器，进入目录执行：

cd dist
./start.sh start

start.sh 自动配置 PHPRC，加载内置 php.ini，自动注入动态库搜索路径。

支持 Webman 原生运维命令：

./start.sh start -d    # 后台守护启动
./start.sh status      # 查看服务状态
./start.sh stop        # 停止服务
./start.sh restart     # 重启服务

# 也可以直接调用包装脚本启动
./webman-server start

📦 产物契约

根据打包命令的不同，构建产物呈现两种专业形态：

形态 1：全静态单二进制产物 (php webman typephp:package --static)

输出纯静态链接（Statically Linked）单一可执行程序，零外部动态库依赖，甚至不需要目标系统存在任何 PHP 环境或 glibc（支持在 Alpine、BusyBox 或任何最小 Linux 容器上直接运行）：

dist/
├── webman-server           # 纯静态链接单二进制 (ELF 64-bit statically linked, stripped，约 17MB)
├── start.sh                # 标准 Workerman 启动脚本（直接 exec ./webman-server "$@"）
├── build-manifest.json     # 输入、镜像与时间等构建元数据
├── config/                 # 业务运行时配置（支持修改配置并动态热生效）
├── public/                 # 静态 Web 资源（HTML、CSS、JS、静态图片等）
├── app/
│   ├── view/               # 视图模板文件（若存在）
│   └── functions.php       # 用户自定义全局函数（若存在）
└── runtime/                # 运行时缓存与日志目录 (logs, views)

核心优势

• 零外部依赖：单文件全静态内嵌，无需 libphp.so、ext/*.so、lib/ 动态库目录或外部 php.ini。
• 跨发行版通用：兼容任意 Linux x86_64 环境（Alpine, Ubuntu, Debian, CentOS, BusyBox 等）。
• 开箱即用：直接运行可执行文件即可启动，免去环境搭建与运维依赖。

极简容器化示例（可选）

得益于纯静态链接，可直接基于仅 5MB 的官方 Alpine 基础镜像构建约 20MB 的超轻量生产镜像：

FROM alpine:latest

WORKDIR /app
COPY dist /app

EXPOSE 8787
CMD ["./webman-server", "start"]

形态 2：动态便携目录产物 (php webman typephp:package)

输出自包含的绿色便携目录，自带预编译 libphp.so 核心运行时与动态扩展，适合需要灵活挂载或使用 Linux 原生 .so 扩展的场景：

dist/
├── webman-server.bin       # TypePHP 生成的 ELF 原生可执行文件（动态链接）
├── webman-server           # 启动包装脚本（自动配置 LD_LIBRARY_PATH 与 PHPRC）
├── start.sh                # 标准 Workerman 启动管理脚本
├── libphp.so               # PHP 核心运行时共享库
├── libphpx.so              # PHPX 运行时共享库
├── php.ini                 # 自包含纯净 PHP 运行时配置
├── ext/                    # 随包分发的 PHP 核心与网络扩展模块 (.so)
├── lib/                    # 随包发布的底层系统与扩展动态依赖库 (通过 ldd 完整收集)
├── build-manifest.json     # 输入、镜像与时间等构建元数据
├── config/                 # 业务运行时配置
├── public/                 # 静态 Web 资源
├── app/
│   ├── view/               # 视图模板（若存在）
│   └── functions.php       # 自定义全局函数（若存在）
└── runtime/                # 运行时缓存与日志目录 (logs, views)

核心优势

• 扩展生态丰富：可使用 Linux 发行版通过 apt/包管理器预编译的海量 .so 扩展，适合依赖特殊外部动态库的项目。
• 分发维护灵活：二进制与底层依赖库（libphp.so / ext/*.so）物理解耦，方便针对性更新。
• 标准 glibc 兼容：兼容 glibc 2.31+ 的任何常见 Linux 发行版（Ubuntu 20.04+, Debian 11+, RHEL 9+ 等）。

🛠️ 全部命令清单

⚙️ 插件配置文件

路径：config/plugin/tinywan/typephp/app.php

return [
    'enable' => true,
    'docker' => [
        'enabled' => true,
        'image' => 'tinywan/typephp-webman-builder:v0.0.17',
    ],
    'build' => [
        'output_name' => 'webman-server',
        'dist_dir' => 'dist',
        'clean_build' => true,
    ],
];

📝 完整构建日志示例

D:\tinywan\typephp\webman> php webman typephp:package
[TypePHP] Preparing build files for Webman project...
[1/3] Verified AOT entrypoint: main.php
[2/3] Generated compiler config: project.linux.yml
[2/3] Generated flattened AOT sources: .typephp/build/helpers.php, .typephp/build/fast-route-functions.php
[2/3] Generated nullable-static AOT sources: .typephp/build/coroutine-context.php, .typephp/build/coroutine-wait-group.php, .typephp/build/coroutine-barrier.php
[2/3] Generated variadic-handler AOT sources: .typephp/build/workerman-worker.php, .typephp/build/workerman-tcp-connection.php, .typephp/build/workerman-async-tcp-connection.php, .typephp/build/workerman-select.php, .typephp/build/webman-file.php
[3/3] Running TypePHP AOT compilation container (tinywan/typephp-webman-builder:v0.0.17)...
Unable to find image 'tinywan/typephp-webman-builder:v0.0.17' locally
Digest: sha256:3d040e8135c92717167434858c23bbfad5cc5563dabd044e5318193cd85aa654
Status: Downloaded newer image for tinywan/typephp-webman-builder:v0.0.17
[INFO] Compiling Linux x86_64 glibc binary (job=8)...
Initialized platform/backend: Linux + GCC (g++)
[Scanning 12/51] app ...
[Scanning 13/51] vendor/workerman/workerman/src ...
[Scanning 14/51] vendor/workerman/webman-framework/src ...
[Scanning 15/51] vendor/workerman/coroutine/src ...
[Scanning 16/51] vendor/psr ...
[Scanning 51/51] vendor/monolog/monolog/src/Monolog/Processor ...
[Analyzing] Pre-checking native class declarations across 173 files...
[Analyzing 1/173] 1% /native/20260907T074248Z-1/main.php
[129/129] 100% native/20260907T074248Z-1/.typephp/build/fast-route-functions.cc
Successfully compiled 129 files
g++ '@/native/20260907T074248Z-1/build/webman_server.rsp' -o '/native/20260907T074248Z-1/build/webman_server' -L'/opt/typephp/vendor/swoole/phpx/lib' -L'/usr/lib' -lphpx -lphp -lgmp -lgmpxx -lmpfr -lstdc++
Build successful: /native/20260907T074248Z-1/build/webman_server
[INFO] Copying PHP extensions from /usr/lib/php/20240924 to dist/ext/ ...
cp: '/native/20260907T074248Z-1/.typephp/out-20260907T074248Z-1/lib/libphp.so' and '/native/20260907T074248Z-1/.typephp/out-20260907T074248Z-1/lib/libphp.so' are the same file
[SUCCESS] Portable directory created: dist (run ./start.sh from it)
🎉 Successfully built portable-dir: dist/webman-server
Run command: cd dist && ./start.sh start

[post] Neutralized phar class constants in 1 config file(s): plugin/webman/console/app.php