启动失败应先执行php bin/hyperf.php start：若报permission denied或command not found，说明入口脚本无执行权限或未引入vendor/autoload.php；class not found多因vendor归属错误或加载路径失效；端口冲突需优先用php bin/hyperf.php stop清理而非kill；zend mm错误通常源于swoole.use_shortname=on未关闭。
启动失败时先看 php bin/hyperf.php start 是否能执行
很多“启动失败”根本没走到框架层，卡在入口脚本权限或加载阶段。直接运行 php bin/hyperf.php start，如果报 Permission denied 或 Command not found，说明 bin/hyperf.php 没有可执行权限或 vendor/autoload.php 未被正确引入。
-
bin/hyperf.php必须有+x权限：执行chmod +x bin/hyperf.php - 检查首行是否为
#!/usr/bin/env php，且第二行是require_once __DIR__ . '/../vendor/autoload.php'; - 别用
php vendor/bin/hyperf.php启动——Hyperf 的bin/hyperf.php是重写过的入口，vendor/bin/下的是 Composer 脚本，不兼容协程环境 - 运行
php -l bin/hyperf.php验证语法，避免因换行符（如 Windows CRLF）导致解析失败
Class not found 大概率是 vendor/ 归属或加载路径错了
报 Class "Hyperf\Contract\ConfigInterface" 或类似找不到类，90% 不是 composer install 没跑，而是 vendor/ 目录归属不对，或入口没走对 autoloader。
- 执行
ls -ld vendor，若显示root root，而 Swoole 进程以www-data运行，就必然失败 - 修复命令：
sudo chown -R $(whoami):$(whoami) vendor/（开发机）；Docker 中应在Dockerfile里RUN chown -R www-data:www-data /app/vendor - 确认
vendor/autoload.php存在且可读：php -r "echo file_get_contents('vendor/autoload.php') ?: 'fail';" - Windows + WSL2 环境下，挂载的 NTFS 目录可能丢失执行位，建议把项目放在 WSL2 原生文件系统（如
/home/xxx/project），而非/mnt/c/...
端口冲突、Address already in use 别急着改配置
报错 failed to listen server port [0.0.0.0:9501], Error: Address already in use [98]，不是配置写错了，而是端口真被占了——而且大概率是你自己上次没关干净的进程。
- 优先执行
php bin/hyperf.php stop，它会发信号给主进程优雅退出；比kill -9安全，也避免残留 worker - 查占用：
lsof -i :9501（macOS/Linux）或netstat -ano | findstr :9501（Windows WSL2） - 若发现 PID 是
php进程但不是 Hyperf，可能是其他 CLI 脚本（比如手动跑的php test.php）启了 Swoole server，得手动 kill - 临时验证？改
config/autoload/server.php中的port值为9502，启动成功再回溯根源
Zend MM unknown error 或直接 segfault，八成是 swoole.use_shortname
这个错误不报堆栈、不指行号，只 crash，新手常以为是代码问题，实际是 PHP 内存管理器被 Swoole 短函数名污染了。
- 必须确保 CLI 环境下
swoole.use_shortname = Off：运行php -i | grep "swoole.use_shortname"，输出必须是Off - 别只改
php.ini，CLI 通常读php-cli.ini，用php --ini确认加载路径 - 验证是否生效：
php -r "var_dump(function_exists('go'));"，返回bool(false)才算关掉 - 宝塔用户注意：即使扩展已启用，也要进「PHP 设置 → 安装扩展」页，点 Swoole 右侧的「设置」，手动关掉 Short Name
vendor/ 属主是 root，同时 swoole.use_shortname 没关，再加一个端口被占——日志里只显示最后那个报错，前面两个问题却一直潜伏着。每次排查，得从 php bin/hyperf.php start 这一行命令开始，一层层剥开。
