webman新手常见问题及解决方法：权限错误需检查start.php路径与可执行权限；路由404须确认route.php配置、命名空间及重启；数据库连接失败因进程常驻，须用连接池且禁用持久化；代码修改无效需执行reload而非restart。

直接上手 Webman，**不用等“学完 PHP”或“搞懂 Workerman 底层”**——只要你会写一个 `echo 'hello'`，就能跑起第一个接口。它不是 Laravel 那种大而全的框架，而是把高性能和简单性焊死在一块的工具。

php start.php start 报错：Permission denied 或 No such file

这是新手卡住的第一道墙，本质是权限或路径问题，不是代码写错了。

• start.php 文件必须在项目根目录下，且有可执行权限（Linux/macOS 执行 chmod +x start.php）
• 如果用 composer create-project 创建项目，start.php 默认存在；但若手动 git clone 后没运行 composer install，vendor/ 目录为空，start.php 会因找不到 autoload.php 而报 Permission denied（实际是 require 失败被 shell 误报）
• Windows 用户别双击 start.php，必须进终端用 php start.php start；WSL2 或 Docker 是更稳的选择

路由写了却 404：Route::get() 没生效

Webman 的路由不自动扫描，config/route.php 是唯一入口，改完必须重启服务。

Webman 2.2.0

Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。

下载

• 确认 route.php 中用了正确的命名空间，比如 use Webman\Route;，不是 use think\Route;
• 控制器类路径要完整，例如 [app\controller\IndexController::class, 'index']，漏掉 app\ 或写成 App\（大小写敏感）都会 404
• 别把路由写在 config/bootstrap.php 或其他地方——只有 config/route.php 被框架主动加载
• 如果访问的是 /api/user 却返回 404，先 curl -X OPTIONS http://localhost:8787/api/user 看是否卡在预检请求上，CORS 中间件必须放在鉴权中间件之前

控制器里连不上数据库：PDO 连接复用导致 MySQL gone away

这是 Webman 和传统 FPM 最根本的区别点：进程常驻，不能在 onWorkerStart 初始化连接。

• 所有数据库操作必须放在请求生命周期内，比如控制器方法、中间件或 service 类的构造函数中
• 不要在 config/bootstrap.php 或 onWorkerStart 回调里写 new PDO() 或 Db::connect()
• 要用连接池（如 webman/database），检查 config/database.php 中 'max_connections' ≥ config/server.php 中的 'worker_num'
• 禁用 'persistent' => true，持久连接在多进程常驻模型下只会制造冲突

修改了代码但页面没变：热更新没生效

Webman 不支持 PHP-FPM 那种“改完即生效”，它的 reload 是进程级的，不是文件监控。

• 改了控制器、中间件、路由后，必须执行 php start.php reload（不是 restart）
• reload 会 fork 新进程并优雅关闭旧进程，零停机；restart 是暴力杀进程再启动，定时任务可能丢失注册
• 改了 config/*.php 也必须 reload，因为配置是在进程启动时一次性加载进内存的
• 开发阶段建议加 -d 参数启动：php start.php start -d，这样控制台会输出详细日志，方便定位哪一行挂了

真正难的不是语法，是接受“PHP 进程可以不退出”这件事。一旦绕过这个认知拐点，后面全是体力活：写路由、写控制器、配中间件——每一步都直来直去，没有魔法，也没有隐藏钩子。