萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP $_SERVER 超全域變數完整參考手冊:參數詳解與實戰應用

$_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_INTERFACECGI 規範版本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_USERHTTP Basic Auth 使用者名稱僅 Apache/ISAPI 模組可用
PHP_AUTH_PWHTTP Basic Auth 密碼同上
PHP_AUTH_DIGESTHTTP 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 工具的基本功。建議收藏本文作為開發時的快速查閱手冊。

copyright © 萬盛學電腦網 all rights reserved