Hyperf 本身不依赖 Apache/Nginx 伪静态规则，因其路由由 PHP 层自主完成；仅在反向代理、SPA fallback 或历史路径兼容等特定场景下，才需 Nginx/Apache 配合 rewrite 或 proxy_pass 转发请求。
Hyperf 是基于 Swoole 的协程框架，本身不依赖 Apache 或 Nginx 的伪静态（rewrite）规则来实现路由——它的路由完全由 PHP 层在启动时注册、运行时匹配，与 Web 服务器的 URL 重写无关。但如果你将 Hyperf 部署在 Nginx（或 Apache）反向代理后，且前端有统一入口（如 SPA 应用），或需要兼容某些历史路径结构，就可能需要配置伪静态规则，确保所有请求都正确转发给 Hyperf 的 HTTP 服务进程。
为什么通常不需要伪静态
Hyperf 默认监听 9501 端口（如 127.0.0.1:9501），它直接处理原始 HTTP 请求，自行解析 PATH_INFO、匹配路由、分发到控制器。只要 Nginx 正确把请求代理过去，Hyperf 就能识别 /api/user/123 这样的路径并完成匹配，无需 rewrite 干预。
只有当出现以下情况时，才需考虑伪静态配合：
当代理已经知道网站路由或内容URL，并且在启动前需要有效的sitemap XML、sitemap索引或robots.txt引用时，请使用sitemap。这是一个发布构件技能，而不是爬虫或SEO平台。
- Nginx 做了非透明代理（比如把
/v1/xxx剥掉前缀再转发，而 Hyperf 路由又没配对应 prefix） - 前端是单页应用（SPA），希望所有未命中 API 的请求都 fallback 到
/index.html，但又不想让 Hyperf 处理静态资源 - 旧系统迁移，URL 规则固定（如
/index.php?r=user/list），需兼容 querystring 风格入口
Nginx 伪静态常见适配场景
假设你用 Nginx 反向代理 Hyperf（监听 127.0.0.1:9501），域名是 api.example.com，以下是几种典型配置方式：
- 纯 API 代理（推荐，默认方式）：不启用 rewrite，只做透传
proxy_pass http://127.0.0.1:9501;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
-
带路径前缀的代理（如统一加
/api）：Nginx 剥离前缀，Hyperf 内部路由按无前缀定义即可
proxy_pass http://127.0.0.1:9501/;
# 注意 proxy_pass 末尾的 /，表示去除 /api/ 后再转发
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
- SPA fallback 场景（前端 + 后端混合部署）：静态资源走 Nginx，API 走 Hyperf，未匹配的路径返回 index.html
try_files $uri $uri/ @hyperf;
}
location @hyperf {
proxy_pass http://127.0.0.1:9501;
proxy_set_header Host $host;
}
Apache 的等效配置（较少用，仅作参考）
若必须用 Apache（不推荐用于生产级 Hyperf），需启用 mod_proxy 和 mod_rewrite，核心是 ProxyPass：
ProxyPass / http://127.0.0.1:9501/
ProxyPassReverse / http://127.0.0.1:9501/
如需兼容 index.php 入口式 URL（例如 /index.php/user/list），可加一条 rewrite 规则，把请求重写为 PATH_INFO 格式再代理，但 Hyerf 原生不解析 index.php 入口，这种模式需额外中间件支持，一般不建议。
关键注意事项
- Hyperf 的路由匹配完全基于
REQUEST_URI或PATH_INFO，Nginx 的proxy_pass是否带斜杠、是否改写Host头，直接影响 Hyperf 收到的路径值 - 不要在 Nginx 中对 API 路径做 rewrite 后再 proxy_pass，除非你明确知道 Hyperf 路由定义与重写后路径一致
- 验证方式：curl -H "Host: api.example.com" http://127.0.0.1:9501/test → 看能否正常响应；再 curl https://api.example.com/test → 对比行为是否一致
- 如果 Hyperf 启用了
TrustedProxies或需要读取真实 IP，务必在 Nginx 中设置X-Forwarded-For和X-Forwarded-Proto
