必须用composer create-project hyperf/hyperf-skeleton创建项目，因hyperf官方不提供脚手架命令且不推荐手动初始化；该命令自动安装依赖、生成runtime/var等目录，并确保配置完整。
Hyperf项目创建必须用composer create-project
Hyperf官方不提供脚手架命令（如hyperf new），也不推荐手动初始化，唯一可靠方式就是通过composer create-project拉取官方 skeleton。直接composer init再逐个require会漏掉关键配置和目录结构，比如config/autoload/下缺失server.php或dependencies.php会导致启动失败。
- 确保已安装 PHP 8.0+ 和 Composer 2.2+
- 运行命令：
composer create-project hyperf/hyperf-skeleton project-name（project-name为你的项目目录名） - 执行后会自动执行
composer install并生成runtime/、var/等必需目录 - 不建议加
--prefer-dist或--no-dev，开发阶段需要dev依赖里的hyperf/devtool来支持热重载
创建后必须立即检查composer.json中的autoload配置
Hyperf依赖PSR-4自动加载，但骨架默认只注册了App命名空间。如果你在app/外新增了模块（比如src/Service/），不手动补全autoload会导致类找不到——错误信息通常是Class "AppServiceXXX" not found，而不是路由或容器报错。
- 打开
composer.json，找到"autoload"段 - 在
"psr-4"下添加你的自定义命名空间，例如："App\Service\": "src/Service/" - 改完后必须运行
composer dump-autoload，否则修改不生效 - 注意路径结尾斜杠：写成
"src/Service"（缺/）会导致自动加载器跳过该目录
php bin/hyperf.php start启动失败的三个高频原因
即使composer create-project成功，php bin/hyperf.php start也常卡住或报错。这不是代码问题，而是环境或权限配置偏差。
- PHP未启用
sockets扩展：Hyperf底层依赖ext-sockets，Ubuntu需sudo apt install php-sockets，macOS用brew install php@8.1（自带sockets） -
bin/hyperf.php没有执行权限：Linux/macOS下需chmod +x bin/hyperf.php，否则提示Permission denied - 端口被占用或无权绑定：默认监听
0.0.0.0:9501，若被占用会报Address already in use；非root用户绑定1024以下端口会失败，此时要改config/autoload/server.php里的port为9501以上
sockets扩展和dump-autoload这步经常被忽略。
