mac装hyperf核心是弃docker、用brew装php≥8.1+源码编译swoole（禁用pecl）、项目创建加--no-interaction、调试必用yasd而非xdebug，并手动在onrequest中加yasd::breakpoint()。
Mac 上装 Hyperf，核心就一条：别用 Docker 做本地开发，直接装原生 PHP + Swoole 扩展，否则你会被文件同步慢、bin/hyperf.php start 启动卡顿、热重载失效反复折磨。
确认 PHP 版本和路径是否干净
Hyperf 要求 PHP >= 7.2，但 macOS 自带的 PHP 已废弃，必须用 brew 管理。常见坑是多个 PHP 版本共存导致 php -v 和 which php 不一致：
- 运行
brew uninstall php清掉旧版本（如有） - 装指定版本，比如
brew install php@8.2（推荐 8.1/8.2，8.3 部分扩展尚未完全适配） - 检查路径是否生效：
echo $PATH看/opt/homebrew/opt/php@8.2/bin是否在最前 - 执行
source ~/.zshrc（或~/.bash_profile）后验证：which php应输出/opt/homebrew/opt/php@8.2/bin/php
编译安装 Swoole 扩展（不是 pecl install）
pecl install swoole 在 Apple Silicon（M1/M2/M3）上大概率失败，报 lib boost not found 或 undefined symbols for architecture arm64。必须源码编译，并显式指定 OpenSSL 和架构参数：
- 先装依赖：
brew install openssl@3 pkg-config - 下载对应版本源码（如
v5.1.3）：wget https://github.com/swoole/swoole-src/archive/refs/tags/v5.1.3.tar.gz - 解压后进入目录，执行：
phpize && ./configure --enable-openssl --with-openssl-dir=/opt/homebrew/opt/openssl@3 --enable-http2 make -j$(sysctl -n hw.ncpu) && sudo make install- 编辑
php.ini（路径用php --ini查）：加两行extension="swoole.so"swoole.use_shortname = "Off"
验证：php --ri swoole 输出里要有 coroutine => enabled 和 http2 => enabled。
创建项目时绕过 Composer 的交互陷阱
composer create-project hyperf/hyperf-skeleton 默认会问你一堆「是否安装 xx 组件」，一不小心按了 y，后续启动就报 Class not found——因为有些组件（如 hyperf/tracer）依赖额外扩展（protobuf），而你没装。
- 强制跳过所有交互：
composer create-project hyperf/hyperf-skeleton myapp --no-interaction - 进项目后，删掉
composer.json里自动加的非必需插件（如hyperf/watcher、hyperf/testing），等真要用再装 - 首次启动前，确保
.env里SWOOLE_HTTP_PORT=9501没被注释，且端口未被占用
启动命令就是 php bin/hyperf.php start，看到 Worker#0 started. 就算成功。用 curl http://127.0.0.1:9501 测试返回 Hello Hyperf.。
调试时注意 yasd 和 PHPStorm 的 ABI 匹配
Mac 上用 PHPStorm 调试 Hyperf，xdebug 基本不可用（协程下断点错乱），必须用 yasd。但它对 PHP 版本极其敏感：
- PHP 8.2 → 必须用
yasd v0.4.0+，老版本（如v0.3.9）会 segfault - 编译 yasd 前，确保
brew install boost，并导出环境变量：export CPLUS_INCLUDE_PATH="/opt/homebrew/opt/boost/include"export LIBRARY_PATH="/opt/homebrew/opt/boost/lib" -
php.ini中写死zend_extension=yasd，不要用绝对路径（/usr/local/lib/php/.../yasd.so容易权限或路径错） - PHPStorm 的 Debug 配置里，「Debug port」必须和
yasd.remote_port一致（默认9000），且勾选「Force break at first line」要关掉——协程初始化阶段断点会卡死进程
真正容易被忽略的是：每次 php bin/hyperf.php start 启动后，yasd 只 attach 到 master 进程，worker 进程里的断点不会触发。想调试请求逻辑，得在 onRequest 回调开头手动加 YASD::breakpoint();。
