Hyperf 3.1 快速入门:环境配置与骨架搭建【新手必看】

云枫君_5397

云枫君_5397

2026-08-09

418人浏览

原创

Hyperf 3.1 启动失败八成因缺失 hyperf/http-server 组件、Swoole shortname 开启或 Windows 原生运行;需手动安装 http-server、禁用 swoole.use_shortname 并在 Linux/macOS 或 Docker 容器中运行。

hyperf 3.1 快速入门:环境配置与骨架搭建【新手必看】

Hyperf 3.1 跑不起来,八成是环境或骨架缺关键组件——不是版本不对,而是hyperf/http-server没装。

PHP 和 Swoole 版本必须匹配

Hyperf 3.1 明确要求 PHP ≥ 8.1、Swoole ≥ 5.0(且不能启用 shortname)。用 php -v 和 php --ri swoole 检查后,重点看两处:

  • swoole.version 是否 ≥ 5.0
  • swow 或 shortname 是否被启用(若输出里有 shortname => On,需在 php.ini 中加 swoole.use_shortname = Off 并重启 PHP)
  • Ubuntu/Debian 用户注意:php-swoole 包通常不满足 Hyperf 3.1 要求,必须源码编译安装 Swoole 5.1+,否则启动时会报 Class 'Swoole\Http\Server' not found

composer create-project 后必须手动装 http-server

官方骨架 hyperf/hyperf-skeleton 默认不含 HTTP 服务组件。跳过这步会导致 php bin/hyperf.php start 静默启动、无监听端口、curl http://127.0.0.1:9501 直接超时。

  • 进入项目根目录后,立刻执行:composer require hyperf/http-server
  • 不要用 composer install 替代——它只装 require-dev 里的东西,而 http-server 是运行时必需依赖
  • 装完检查 composer.json 的 require 字段是否已含 "hyperf/http-server": "^3.1"

注解路由 prefix 写法容易错

#[AutoController(prefix: '/api')] 是对的,#[AutoController(prefix: '/api/')] 是错的——末尾斜杠会导致实际访问路径变成 /api//index,404。

hyperframes-超帧视频
hyperframes-超帧视频

HTML 驱动的视频合成——GSAP 动画、TTS 字幕、音频响应、着色器转场

下载
  • Hyperf 的注解路由 prefix 是「前缀拼接」,不是「路径匹配前缀」
  • 方法级路径(如 public function index())会被自动映射为 GET /,最终完整路径 = prefix + method path
  • 若控制器内定义了多个方法,建议统一用 #[GetMapping] 等显式注解,避免隐式行为干扰调试

Windows 下别硬刚本地环境

Hyperf 官方不支持 Windows 原生运行(Swoole 在 Win 上不可用),所谓“能跑”基本是 Docker 模拟出来的。但 Docker for Windows 家庭版常因 WSL2 兼容性问题卡在 bin/hyperf.php start 不返回。

  • 推荐方案:用 docker run -it -v $(pwd):/app -p 9501:9501 hyperf/hyperf:8.2-alpine-v3.16-swoole 进入容器后,再 cd /app && composer create-project hyperf/hyperf-skeleton .
  • 切忌在宿主机用 php bin/hyperf.php start —— 即使提示 “Server started”,也大概率只是协程调度器初始化成功,HTTP Server 根本没注册
  • Mac 用户也建议关掉 Docker 文件共享,直接本地跑;Win 用户接受「开发在容器、调试用 VS Code Remote-Container」这个现实

真正卡住新手的从来不是语法,而是 http-server 缺失、Swoole shortname 开启、Windows 本地直跑这三件事——它们不会报明显错误,只会让服务「看起来启动了,实则没监听」。

相关文章

PHP速学视频免费教程(入门到精通)
PHP速学视频免费教程(入门到精通)

PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

下载

本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

相关专题

更多
Hyperf协程并发编程实操指南
Hyperf协程并发编程实操指南

本专题深度解析 Hyperf 协程底层机制,解决协程环境下全局变量污染、Context 上下文丢失等核心痛点,提供规范化的 PHP 高并发编程实战代码建议。

2026.05.19

220

15

深入理解Hyperf AOP切面与注解使用
深入理解Hyperf AOP切面与注解使用

详尽介绍 Hyperf 依赖注入容器与 AOP 面向切面编程的使用技巧,包含自定义注解开发流程及注解不生效的排查方案,助力开发者掌握框架核心架构。

2026.05.19

504

16

Hyperf 数据库操作与连接池优化方案
Hyperf 数据库操作与连接池优化方案

针对 Hyperf Eloquent 模型在大数据量下的表现进行深度优化,讲解连接池断线重连、超时设置及事务处理等生产环境常见技术疑难。

2026.05.19

264

15

基于 Hyperf 的微服务架构集成实战
基于 Hyperf 的微服务架构集成实战

本专题涵盖 Hyperf 微服务全栈解决方案,包括服务注册与发现、配置中心集成、JsonRPC 调用以及分布式限流熔断的落地实践。

2026.05.19

356

18

Hyperf 高并发缓存与分布式系统应用
Hyperf 高并发缓存与分布式系统应用

讲解在协程模式下如何高效操作 Redis,实现高性能分布式锁、处理缓存击穿/雪崩问题,并提供基于 Hyperf 的分布式事务处理思路。

2026.05.19

608

15

Hyperf 项目部署运维与性能调优手册
Hyperf 项目部署运维与性能调优手册

聚焦 Hyperf 在生产环境的落地,包含 Docker 高效打包、Swoole 配置优化、常见的内存溢出(OOM)问题排查方法以及热更新方案。

2026.05.19

585

15

Hyperf PHP 微服务框架高性能开发实战
Hyperf PHP 微服务框架高性能开发实战

本专题围绕 Hyperf 框架展开,讲解微服务架构设计、协程异步处理、服务注册与发现、RPC 通信及性能优化策略。通过完整项目示例,帮助开发者构建高效、稳定、可扩展的 PHP 分布式服务系统。

2026.06.08

216

23

GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

2026.11.17

20

15

GoFrame框架安装与gf命令行工具
GoFrame框架安装与gf命令行工具

本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.17

20

15

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
Hyperf官方中文手册(3.1)
Hyperf官方中文手册(3.1)

共0课时 | 0人学习

Swoole系列-从0到1-新手进阶
Swoole系列-从0到1-新手进阶

共29课时 | 2.4万人学习