Composer无法直接安装Gearman C扩展，必须先用pecl install gearman编译安装依赖libgearman的PHP扩展，并在php.ini中启用extension=gearman.so，再通过composer require php-gearman/php-gearman引入封装类库。
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
立即学习“PHP免费学习笔记（深入）”；
- 该包提供
PhpGearman\Client、PhpGearman\Worker等类，本质仍是调用gearman_client_add_server()等原生函数 - 不建议用
symfony/process或amqp替代 Gearman——它们协议不同，worker 不互通 - 若项目用 Laravel，可配合
laravel-gearman，但它底层仍依赖php-gearman和 C 扩展
GearmanClient 连接失败的三个高频原因及验证方式
即使 C 扩展装好了，GearmanClient 初始化后调用 addServer() 仍可能静默失败，任务发不出去。
- 默认端口是
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 服务——这些点漏掉任何一个，分布式任务分发就只是个幻觉。
