Webman不是传统PHP框架，而是基于Workerman的常驻内存、异步非阻塞HTTP服务框架，其高性能源于常驻内存架构与事件驱动模型，避免FPM模式下重复初始化开销。
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。
立即学习“PHP免费学习笔记（深入）”；
- 检查
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并记录日志，否则异常静默丢失，极难定位
Webman 的“高性能”来自对底层 Workerman 的直接复用，但也意味着它不会帮你兜底——比如自动重连数据库、自动处理协程上下文、自动清理僵尸连接。这些都得你亲手设计，而不是期待框架替你决定。
