$_SERVER 是 PHP 最核心的超全域陣列之一,包含伺服器環境、請求資訊、執行上下文等關鍵資料。本文系統整理所有常用鍵值,分類說明用途、回傳值格式與實戰應用場景,並補充安全性注意事項。
請求相關資訊
| 鍵名 | 說明 | 範例值 | 備註 |
REQUEST_METHOD |
HTTP 請求方法 |
GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH |
RESTful API 必檢 |
REQUEST_URI |
請求 URI(含查詢字串) |
/api/user/123?fields=name,email |
路由解析核心依據 |
QUERY_STRING |
查詢字串(? 之後內容) |
fields=name,email&page=1 |
不含 # fragment |
HTTP_REFERER |
來源頁面 URL |
https://example.com/list |
不可信,用戶可偽造/瀏覽器不送 |
HTTP_USER_AGENT |
用戶代理字串 |
Mozilla/5.0 (Windows NT 10.0; Win64; x64)... |
裝置偵測、爬蟲識別、統計分析 |
HTTP_ACCEPT |
可接受的回應內容型別 |
text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 |
內容協商依據 |
HTTP_ACCEPT_LANGUAGE |
偏好語言 |
zh-TW,zh;q=0.9,en-US;q=0.8,en;q=0.7 |
多語系自動切換 |
HTTP_ACCEPT_ENCODING |
支援的壓縮編碼 |
gzip, deflate, br |
決定是否啟用壓縮輸出 |
HTTP_HOST |
請求 Host 標頭 |
api.example.com:8080 |
虛擬主機識別、生成絕對 URL |
CONTENT_TYPE |
請求內容型別 |
application/json, multipart/form-data |
非 GET 請求必檢 |
CONTENT_LENGTH |
請求主體長度(位元組) |
1024 |
限制上傳大小 |
腳本路徑與執行環境
| 鍵名 | 說明 | 範例值 | 差異重點 |
SCRIPT_FILENAME |
當前執行腳本絕對路徑 |
/var/www/html/index.php |
最可靠的「當前檔案」路徑 |
SCRIPT_NAME |
相對網站根目錄的腳本路徑 |
/index.php |
生成自我參考 URL |
PHP_SELF |
相對網站根目錄的腳本路徑 |
/index.php |
含 PATH_INFO,XSS 風險,表單 action 勿直接用 |
DOCUMENT_ROOT |
網站文檔根目錄 |
/var/www/html |
組合絕對路徑基準 |
PATH_INFO |
腳本名稱後的額外路徑資訊 |
/user/123(訪問 /index.php/user/123) |
RESTful 路由核心,需伺服器支援 |
PATH_TRANSLATED |
PATH_INFO 對應的檔案系統路徑 |
/var/www/html/user/123 |
較少用,CGI 規範殘留 |
關鍵差異:SCRIPT_NAME vs PHP_SELF
// 訪問:https://example.com/test.php/foo/bar?a=1
$_SERVER['SCRIPT_NAME'] // "/test.php"
$_SERVER['PHP_SELF'] // "/test.php/foo/bar" ← 含 PATH_INFO
$_SERVER['REQUEST_URI'] // "/test.php/foo/bar?a=1"
安全警示:PHP_SELF 可被注入惡意腳本(/test.php/),表單 action 必須用 htmlspecialchars($_SERVER['PHP_SELF']) 或留空/用 SCRIPT_NAME。
伺服器與網路資訊
| 鍵名 | 說明 | 範例值 |
SERVER_ADDR | 伺服器 IP 位址 | 192.168.1.100 |
SERVER_NAME | 伺服器主機名(ServerName 設定值) | example.com |
SERVER_PORT | 伺服器監聽埠 | 80, 443, 8080 |
SERVER_PROTOCOL | 通訊協定版本 | HTTP/1.1, HTTP/2.0 |
SERVER_SOFTWARE | 伺服器軟體識別 | nginx/1.24.0, Apache/2.4.58 |
GATEWAY_INTERFACE | CGI 規範版本 | CGI/1.1 |
SERVER_ADMIN | 管理員 Email(Apache 設定) | admin@example.com |
SERVER_SIGNATURE | 伺服器版本與虛擬主機名字串 | <address>Apache/2.4.58 Server at example.com Port 80</address> |
客戶端連線資訊
| 鍵名 | 說明 | 範例值 | 注意事項 |
REMOTE_ADDR |
客戶端 IP |
203.0.113.45 |
代理/負載均衡下為代理 IP,需配合 X-Forwarded-For |
REMOTE_HOST |
客戶端主機名 | client.example.com |
需啟用 HostnameLookups On,效能影響大,通常關閉 |
REMOTE_PORT |
客戶端連線埠 | 54321 |
臨時埠,識別同一 IP 不同連線 |
取得真實客戶端 IP 的最佳實踐
function getRealClientIp(): string {
$proxyHeaders = [
'HTTP_X_FORWARDED_FOR', // 標準代理標頭,可能包含多個 IP:client, proxy1, proxy2
'HTTP_X_REAL_IP', // Nginx 常用
'HTTP_CLIENT_IP', // 部分代理使用
'HTTP_CF_CONNECTING_IP', // Cloudflare
'HTTP_TRUE_CLIENT_IP', // Akamai/Cloudflare Enterprise
];
foreach ($proxyHeaders as $header) {
if (!empty($_SERVER[$header])) {
// 取第一個非私有 IP
$ips = array_map('trim', explode(',', $_SERVER[$header]));
foreach ($ips as $ip) {
if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE)) {
return $ip;
}
}
// 全是私有 IP,回傳第一個
return $ips[0];
}
}
return $_SERVER['REMOTE_ADDR'] ?? '0.0.0.0';
}
HTTPS 與認證相關
| 鍵名 | 說明 | 備註 |
HTTPS | 非空值表示 HTTPS 請求(通常為 on) | Nginx 需設定 fastcgi_param HTTPS on; |
PHP_AUTH_USER | HTTP Basic Auth 使用者名稱 | 僅 Apache/ISAPI 模組可用 |
PHP_AUTH_PW | HTTP Basic Auth 密碼 | 同上 |
PHP_AUTH_DIGEST | HTTP Digest Auth Authorization 標頭內容 | Apache 模組 |
AUTH_TYPE | 認證類型 | Basic, Digest |
命令列模式專用
| 鍵名 | 說明 |
argv | 參數陣列,$argv[0] 為腳本名 |
argc | 參數個數(含腳本名) |
REQUEST_TIME | 請求開始時間戳(PHP 5.1+) |
REQUEST_TIME_FLOAT | 請求開始微秒時間戳(PHP 5.4+) |
實戰應用範例
1. 通用 URL 產生器
function currentUrl(bool $withQuery = true): string {
$scheme = (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off') ? 'https' : 'http';
$host = $_SERVER['HTTP_HOST'] ?? $_SERVER['SERVER_NAME'] ?? 'localhost';
$uri = $_SERVER['REQUEST_URI'] ?? '/';
return $scheme . '://' . $host . ($withQuery ? $uri : parse_url($uri, PHP_URL_PATH));
}
2. 跨域(CORS)預檢處理
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type, Authorization');
header('Access-Control-Max-Age: 86400');
exit(0);
}
3. 條件式請求處理
$etag = md5_file($_SERVER['SCRIPT_FILENAME']);
if (isset($_SERVER['HTTP_IF_NONE_MATCH']) && $_SERVER['HTTP_IF_NONE_MATCH'] === $etag) {
header('HTTP/1.1 304 Not Modified');
exit;
}
header("ETag: $etag");
4. 開發環境除錯資訊面板
if (($_SERVER['SERVER_ADDR'] ?? '') === '127.0.0.1' || ($_SERVER['REMOTE_ADDR'] ?? '') === '127.0.0.1') {
echo '';
print_r(array_filter($_SERVER, fn($k) => !str_starts_with($k, 'HTTP_'), ARRAY_FILTER_USE_KEY));
echo '';
}
安全性重點總結
- 所有
HTTP_* 鍵值來自客戶端標頭,完全不可信,使用前必須驗證/過濾
PHP_SELF 直接輸出到 HTML 會導致 XSS,必須 htmlspecialchars()
REMOTE_ADDR 在反向代理架構下不準確,需配合可信代理清單解析 X-Forwarded-For
- 不要將
$_SERVER 完整輸出到日誌/頁面,包含敏感路徑、內部 IP、認證資訊
REQUEST_URI 含查詢字串,重導向時注意避免開放式重導向漏洞
總結
$_SERVER 是 PHP 應用與執行環境溝通的橋樑。熟悉各鍵值含義、差異(特別是 SCRIPT_NAME/PHP_SELF/REQUEST_URI)、可信度分級與安全處理,是開發健壯 Web 應用、API 服務、CLI 工具的基本功。建議收藏本文作為開發時的快速查閱手冊。