生产环境必须用 Linux 或 macOS，Windows 直接上 WSL2；Swoole 扩展未正确加载是 90% 启动失败的根源。验证需检查 php --ri swoole 中 coroutine 是否启用、版本是否 ≥5.1.0、Alpine 下是否执行 docker-php-ext-enable swoole。
生产环境必须用 Linux 或 macOS，Windows 直接上 WSL2；Swoole 扩展未正确加载是 90% 启动失败的根源。
如何验证 Swoole 是否已就绪
别只看 php -m | grep swoole 输出有就放心——它可能没启用协程支持，或版本不匹配。关键检查点有三个：
-
php --ri swoole输出中必须含coroutine => enabled和swoole.use_shortname => Off - Swoole 版本需 ≥ 5.1.0（Hyperf v3.1+ 强制要求），
SWOOLE_VERSION常量值要对得上 - 若用 Alpine 镜像，确认
pecl install swoole后执行了docker-php-ext-enable swoole，否则扩展不会写入php.ini
常见错误现象：PHP Fatal error: Uncaught Swoole\Exception: Swoole extension is not loaded 或启动后立即退出，基本都卡在这一步。
server.php 中 worker_num 和 max_coroutine 怎么设
这两个参数不是越大越好，设错反而引发内存溢出或调度延迟。真实线上调优逻辑是：
立即学习“PHP免费学习笔记（深入）”；
-
worker_num推荐设为swoole_cpu_num() * 2，但上限不超过 64；超核数部署在单机上收益递减，还挤占其他服务资源 -
max_coroutine要结合单请求平均协程数预估：比如一个 HTTP 请求平均启 5 个协程（DB + Redis + HTTP Client），QPS 峰值 2000，则最低需 10000；建议从 20000 起步，观察coroutine_stats指标是否频繁接近上限 - 别忽略
buffer_output_size，大文件响应或长连接流式传输时，2 * 1024 * 1024是安全下限，否则可能触发ERROR #1007: send buffer overflow
Docker 部署时 vendor 目录怎么处理才不踩坑
直接 COPY . . 然后容器内 composer install 是最常犯的错误——镜像层污染、缓存失效、权限混乱全来了。正确做法只有两种：
- 多阶段构建：第一阶段用完整 PHP 镜像装依赖，第二阶段仅
COPY --from=builder /app/vendor /app/vendor，体积可压到 150MB 内 - 宿主机预装：开发机上跑
composer install --no-dev --optimize-autoloader，再COPY整个vendor/，确保composer.lock与运行环境完全一致 - 绝对禁止在生产镜像里留
composer二进制或dev包，opcache.enable_cli=1和opcache.preload在HYPERF_ENV=prod下才生效
配置热更新为什么经常失效
挂载 ./config:/app/config:ro 看似合理，但 Hyperf 默认会把 autoload 下的 PHP 配置编译成 runtime/container/proxy 文件，改了 config 文件不重启服务根本不会重载。真正可控的方式只有：
- 用
HYPERF_ENV=prod启动，配合php bin/hyperf.php server:watch—— 它监听的是config/和app/下所有 PHP 文件变化，触发自动 reload - 若必须挂载配置，得同步挂载
runtime/目录（且确保容器内www-data用户有写权限），否则 proxy 类生成失败，报Class not found -
.env文件不能靠挂载覆盖APP_ENV，它只在首次启动时读取；环境切换必须通过ENV_FILE指定不同文件，或直接传环境变量
最易被忽略的一点：所有配置变更（哪怕只是改了个数据库密码）都必须触发 runtime 目录重建，否则旧代理类还在内存里跑着——这不是 bug，是 Hyperf 的设计前提。
