如何通过Composer安装 Gearman 库在 PHP 中实现分布式任务分发-composer-PHP中文网

composer无法直接安装gearman c扩展，必须先用pecl install gearman编译安装依赖libgearman的php扩展，并在php.ini中启用extension=gearman.so，再通过composer require php-gearman/php-gearman引入封装类库。

如何通过composer安装 gearman 库在 php 中实现分布式任务分发

Composer 安装 `gearman` 扩展前必须先装 C 扩展，纯 PHP 包不工作

直接运行 composer require gearman/gearman 或类似包会失败——因为 Gearman 在 PHP 中依赖底层 C 扩展 gearman（由 libgearman 提供），不是纯 PHP 实现。Composer 只能装 PHP 类库，但真正通信、连接、任务投递都靠这个 C 扩展支撑。

常见错误现象：Class 'GearmanClient' not found 或 Call to undefined function gearman_client_create()，说明扩展根本没加载。

先确认系统已安装 libgearman-dev（Ubuntu/Debian）或 gearmand-devel（CentOS/RHEL）
再用 pecl install gearman 编译安装 PHP 扩展（注意匹配 PHP 版本，如 PHP 8.1 需用 gearman 2.0.6+）
检查 php.ini 是否启用：确认有 extension=gearman.so（Linux/macOS）或 extension=php_gearman.dll（Windows）
重启 Web 服务或 CLI PHP 进程，运行 php -m | grep gearman 验证是否加载成功

用 Composer 装 PHP 封装类库时，选 `php-gearman` 而非过时的 `gearman/gearman`

官方 gearman/gearman 包早已废弃（最后一次更新是 2013 年），PHP 7+ 下无法兼容。目前稳定可用的是社区维护的 php-gearman/php-gearman，它只是对原生 C 扩展的轻量封装，不替换底层逻辑。

执行：composer require php-gearman/php-gearman

该包提供 PhpGearman\Client、PhpGearman\Worker 等类，本质仍是调用 gearman_client_add_server() 等原生函数
不建议用 symfony/process 或 amqp 替代 Gearman——它们协议不同，worker 不互通
若项目用 Laravel，可配合 laravel-gearman，但它底层仍依赖 php-gearman 和 C 扩展

`GearmanClient` 连接失败的三个高频原因及验证方式

即使 C 扩展装好了，GearmanClient 初始化后调用 addServer() 仍可能静默失败，任务发不出去。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

默认端口是 4730，但 gearmand 服务未启动：运行 gearmand -d -l /var/log/gearman.log 启动守护进程
防火墙拦截：检查 sudo ufw status（Ubuntu）或 sudo firewall-cmd --list-ports（CentOS），放开 4730/tcp
客户端连错地址：不要写 localhost（可能解析为 IPv6 ::1），改用 127.0.0.1；Docker 场景下 worker 和 client 在不同容器时，server 地址应填 gearmand 容器名或宿主机 IP

快速验证：用 telnet 127.0.0.1 4730 能通即说明服务可达；再用 gearadmin --status 查看当前 job 数和 worker 注册状态。

任务分发时 `doBackground()` 和 `doNormal()` 的行为差异直接影响可靠性

很多人用 doNormal() 发任务，结果发现 client 卡住、超时、worker 没收到——这是同步阻塞模式的正常表现，不是 bug。

doNormal()：client 等待 worker 执行完并返回结果才继续，网络抖动或 worker 崩溃会导致 client 长时间 hang
doBackground()：client 发完就返回 job handle（如 G-:job_abc123），适合高吞吐场景；但需额外轮询 jobStatus() 或监听 gearmand 日志来确认完成
若需失败重试，别依赖 client 端重发——gearmand 本身不保证 delivery，应在 worker 内部做幂等 + 重试，或用外部队列兜底

真正分布式的关键不在“发出去”，而在 worker 如何注册、如何被负载均衡、如何容错退出——这些都得靠 gearmand 的 server-side 调度逻辑，PHP 层只负责收发字节流。

扩展没装对，后面所有代码都是空转；连不上 gearmand，封装再漂亮也推不动一个 job；同步调用在生产环境极易拖垮 client 服务——这些点漏掉任何一个，分布式任务分发就只是个幻觉。