PHP无法直接通过$_SERVER获取所有原始请求头，因CGI/PHP-FPM会重写或过滤带短横线/下划线的自定义头（如X-Api-Key、Authorization）；应优先使用getallheaders()获取原始头，不可用时再回退到$_SERVER手动映射，并需针对Nginx/Apache配置透传规则。
PHP 无法直接通过 $_SERVER 获取所有原始请求头，尤其是带下划线或短横线的自定义头（如 X-Api-Key、Authorization），因为 CGI/PHP-FPM 会重写或过滤部分键名。必须用对方法，否则拿到的是空值或被转换后的错误键。
为什么 $_SERVER['HTTP_X_API_KEY'] 有时拿不到值
Apache 和 Nginx 对请求头的处理逻辑不同，且 PHP 默认会把头字段转成大写 + 下划线格式（如 X-Api-Key → HTTP_X_API_KEY），但前提是该头没被 Web 服务器拦截或重写。常见失效原因：
- Nginx 默认不传递含短横线的自定义头，需显式配置
underscores_in_headers on;并用proxy_set_header转发 - Apache 的
mod_security或某些安全模块会静默丢弃Authorization等敏感头 - PHP 运行在 CGI/FastCGI 模式下时，
HTTP_前缀可能被截断（如getallheaders()更可靠） - 前端用
fetch发送Authorization头但未设credentials: 'include'，预检失败导致头未发送
getallheaders() 是最稳妥的获取方式（但有兼容性限制）
该函数原生返回全部原始请求头，键名保持客户端发送时的大小写和符号（如 Authorization、X-Request-ID），不经过 $_SERVER 映射。但它不是全环境可用：
- 仅在 Apache、Nginx + PHP-FPM（配合
fastcgi_param配置）下稳定工作 - CLI 模式或某些嵌入式 SAPI 下会报
undefined function - 若不可用，必须回退到
$_SERVER手动映射
if (function_exists('getallheaders')) {
$headers = getallheaders();
$auth = $headers['Authorization'] ?? null;
$apiKey = $headers['X-Api-Key'] ?? null;
} else {
// 回退方案：手动从 $_SERVER 提取
$headers = [];
foreach ($_SERVER as $key => $value) {
if (str_starts_with($key, 'HTTP_')) {
$name = str_replace(['HTTP_', '_'], ['','-',], ucwords(strtolower(str_replace('_', '-', substr($key, 5)))));
$headers[$name] = $value;
}
}
}获取 Authorization 头要绕过 Web 服务器限制
Apache 和 Nginx 默认不把 Authorization 头传给 PHP，尤其在 Basic 或 Bearer 场景下极易踩坑：
HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
立即学习“PHP免费学习笔记（深入）”；
- Nginx 需加两行：
fastcgi_pass_request_headers on; proxy_set_header Authorization $http_authorization;（后者用于反向代理场景） - Apache 需启用
mod_rewrite并添加：RewriteEngine On RewriteCond %{HTTP:Authorization} ^(.*) RewriteRule .* - [e=HTTP_AUTHORIZATION:%1] - PHP 内部检测时，别只查
$_SERVER['HTTP_AUTHORIZATION']，优先用getallheaders()['Authorization']
自定义头命名与接收的大小写陷阱
HTTP 协议规定头名不区分大小写，但 PHP 的 getallheaders() 返回键名完全取决于客户端发送时的原始拼写（如 x-api-key、X-Api-Key、X-API-KEY 都可能）。实际开发中：
- 前端应统一用 PascalCase（
X-Api-Key）或 kebab-case（x-api-key），避免混用 - PHP 接收时建议做标准化处理：
$headers = getallheaders() ?: []; $apiKey = $headers['X-Api-Key'] ?? $headers['x-api-key'] ?? $headers['X-API-KEY'] ?? null;
- 不要依赖
$_SERVER['HTTP_X_API_KEY']在所有环境下都存在——它在 CLI、某些容器化部署或旧版 PHP 中根本不会生成
真正难的不是写几行代码读头，而是确认头从客户端发出后，是否完整穿过 Nginx/Apache、是否被安全模块拦截、是否在 PHP SAPI 层被重写。每次换部署环境，都要重新验证 getallheaders() 是否可用，以及 Authorization 是否真能抵达你的脚本。
