webman启动失败需按五步排查：一、升级php至8.0+并验证版本；二、启用pcntl和posix扩展；三、配置composer国内源并执行composer install --no-dev；四、windows用户须用wsl2或docker运行；五、检查端口占用、修改监听端口并确保runtime/目录可写。
如果您尝试启动Webman项目，但命令执行失败或提示PHP扩展缺失、版本不符，则很可能是本地PHP环境配置未达标。以下是解决此问题的步骤：
一、验证并升级PHP版本
Webman要求PHP最低版本为7.4，推荐使用PHP 8.0+以获得完整功能支持和最佳性能。低于该版本将导致composer install失败或运行时抛出Fatal error。
1、在终端中执行php -v，确认当前PHP版本号。
2、若版本低于7.4，需卸载旧版并安装新版：Ubuntu系统执行sudo apt update && sudo apt install php8.0-cli php8.0-mbstring php8.0-xml php8.0-zip php8.0-pcntl php8.0-posix php8.0-sqlite3；CentOS系统执行sudo yum install php80-php-cli php80-php-mbstring php80-php-xml php80-php-zip php80-php-pcntl php80-php-posix php80-php-sqlite3。
3、执行sudo update-alternatives --config php，选择刚安装的PHP 8.0路径并设为默认。
4、再次运行php -v，确认输出中显示PHP 8.0.x 或更高版本且无警告信息。
二、启用必需的PHP扩展
Webman依赖pcntl与posix扩展实现多进程管理，缺少任一扩展将导致start.php无法以守护模式启动，仅能短暂运行后退出。
1、执行php -m | grep -E "pcntl|posix"，检查两个扩展是否已加载。
2、若未列出，Ubuntu用户执行sudo phpenmod pcntl posix；CentOS用户需编辑/etc/php.d/目录下对应ini文件，取消extension=pcntl.so和extension=posix.so前的分号注释。
3、重启PHP CLI服务（如适用）或直接验证：php -r "echo extension_loaded('pcntl') && extension_loaded('posix') ? 'ok' : 'fail';"，返回ok表示成功。
三、配置Composer并安装项目依赖
Composer是Webman依赖管理的核心工具，错误的镜像源或权限设置会导致install卡死、包下载失败或vendor目录结构异常。
1、执行composer --version，确保Composer版本不低于2.0；若未安装，使用curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer安装。
2、切换国内镜像源提升稳定性：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。
3、进入项目根目录，执行composer install --no-dev，禁止添加--ignore-platform-reqs参数，否则将跳过PHP版本与扩展校验，埋下运行时隐患。
4、观察输出末尾是否出现"Generating autoload files"及"Installing dependencies"完成提示，无红色ERROR字样。
四、修正Windows平台特殊限制
Windows系统不原生支持pcntl和posix扩展，直接运行php start.php start会报错“pcntl extension is not loaded”，此时必须改用兼容方案而非强行启用扩展。
1、确认PHP运行于WSL2或Docker容器内——这是Windows下唯一可稳定启用pcntl的合法方式。
2、若使用WSL2，先在Ubuntu子系统中安装PHP 8.0及扩展，再将Webman项目目录挂载至/mnt/c/路径下，从WSL终端执行php start.php start。
3、若使用Docker，创建docker-compose.yml，指定php:8.0-cli镜像，挂载本地项目目录至容器/www，并在容器内执行启动命令。
4、严禁在Windows原生命令行中尝试通过pecl安装pcntl，该操作必然失败且破坏PHP环境。
五、检查并修复端口冲突与权限问题
Webman默认监听8787端口，若该端口被占用或当前用户无权绑定，start.php将提示"Address already in use"或"Permission denied"，服务无法进入常驻状态。
1、Linux/macOS执行sudo lsof -i :8787或netstat -tulpn | grep :8787，定位占用进程PID。
2、终止冲突进程：kill -9 PID，或修改config/server.php中server选项的listen字段为其他可用端口如8788。
3、确保项目目录及其子目录对当前用户具有读写权限：chmod -R 755 . && chmod -R 777 runtime/，其中runtime/必须可写，否则日志与PID文件无法生成。
4、首次启动时使用php start.php start -d进行调试模式运行，观察终端实时输出，确认无Failed to bind address类错误。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
