Webman高性能PHP开发避坑指南_新手常犯的10个错误总结【启示】-php教程-PHP中文网

Webman不是传统PHP框架，而是基于Workerman的常驻内存、异步非阻塞HTTP服务框架，其高性能源于常驻内存架构与事件驱动模型，避免FPM模式下重复初始化开销。

webman高性能php开发避坑指南_新手常犯的10个错误总结【启示】

Webman 不是 Laravel，也不是 ThinkPHP；它轻量、原生、依赖少，但正因如此，新手照搬其他框架习惯，反而最容易翻车。

Webman 启动失败却没报错？检查 `php.ini` 和 `workerman` 扩展兼容性

Webman 基于 Workerman，而 Workerman 严重依赖 pcntl、posix 和 sockets 这三个扩展。Windows 下默认不支持 pcntl，所以本地开发用 WSL 或 Docker 是刚需，不是“可选优化”。

运行 php -m | grep -E "(pcntl|posix|sockets)" 确认三者全部启用
若用 Docker，镜像必须基于 Linux（如 php:8.2-cli），不能用 php:8.2-apache —— Webman 不走 Apache/Nginx 的 CGI 模式
php.ini 中禁用 opcache.enable_cli=0（CLI 模式下 OPcache 默认关闭，但某些定制镜像会误开，导致热更新失效）

`onWorkerStart` 里写数据库连接，为什么总连不上？

Webman 的 onWorkerStart 在主进程启动后、子进程 fork 前执行，此时连接句柄会被所有子进程继承，造成连接复用冲突或 MySQL 报错 MySQL server has gone away。

数据库连接必须放在 onMessage、onConnect 或自定义服务的构造函数中（即每个子进程独立初始化）
若要用连接池（如 webman/database 插件），确保配置项 max_connections 与 Workerman 的 worker_num 匹配，避免连接数爆炸
别在 onWorkerStart 里调 new PDO() 或 Db::connect() —— 这是高频翻车点

路由匹配不到，`GET /api/user` 返回 404？确认路径和中间件顺序

Webman 路由是严格前缀匹配，且中间件执行顺序直接影响请求能否进入路由逻辑。常见错误是把鉴权中间件放在了路由定义之前，而该中间件又未放行 OPTIONS 预检请求，导致 CORS 场景下直接 404。

btpanel phpsite 宝塔面板PHP网站

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

下载

检查 config/route.php 中是否漏写 ->middleware(...)，或误将中间件数组写成字符串（如 'auth' 而非 [AuthMiddleware::class]）
RESTful 路由需显式启用：Route::group('/api', function () { ... })->middleware([CorsMiddleware::class]);
静态资源（如 /static/xxx.js）若被前置中间件拦截，也会 404 —— 建议把静态文件托管给 Nginx，而非交由 Webman 处理

WebSocket 连接后立刻断开？查 `onOpen` 是否抛异常或阻塞

Webman WebSocket 的 onOpen 回调一旦抛出未捕获异常，或执行耗时操作（如同步 Redis 查询、大文件读取），会导致连接被 Workerman 主动关闭，客户端看到的是 “connection closed before receiving a handshake response”。

onOpen 内禁止使用 sleep()、file_get_contents() 或任何同步 I/O
需要校验 token？改用异步 Redis 客户端（如 webman/redis + co\run()）或提前在 HTTP 握手阶段完成（通过 onHandshake）
务必在 onOpen 开头加 try/catch 并记录日志，否则异常静默丢失，极难定位