前後端分離架構中,JavaScript encodeURIComponent 與 PHP urlencode 對空格、波浪號等字元編碼結果不同(前者編為 %20,後者為 +),導致簽名驗證失敗、參數解析錯誤。本文提供雙向相容的自訂編解碼函數,確保前後端編碼行為一致。
| 字元 | JS encodeURIComponent | PHP urlencode | PHP rawurlencode |
|---|---|---|---|
| 空格 | %20 | + | %20 |
| ~ | ~ (不編碼) | %7E | ~ (不編碼) |
| ! | %21 | %21 | %21 |
| ' | %27 | %27 | %27 |
| ( | %28 | %28 | %28 |
| ) | %29 | %29 | %29 |
結論:PHP 應使用 rawurlencode/rawurldecode 以符合 RFC 3986,與 JS 行為一致。
若必須相容舊系統的 urlencode 行為(空格→+),提供以下封裝:
<?php
/**
* 相容 JavaScript encodeURIComponent 行為(RFC 3986)
*/
function ajaxEncode(string $str): string {
return rawurlencode($str);
}
function ajaxDecode(string $str): string {
return rawurldecode($str);
}
/**
* 相容 PHP 老版 urlencode 行為(空格→+)
* 僅在對接無法修改的舊系統時使用
*/
function legacyEncode(string $str): string {
return str_replace('%20', '+', rawurlencode($str));
}
function legacyDecode(string $str): string {
return rawurldecode(str_replace('+', ' ', $str));
}
/**
* 針對表單提交(application/x-www-form-urlencoded)的特殊處理
* 只編碼 &, =, % 三個會破壞結構的字元
*/
function formEncode(string $str): string {
return strtr($str, [
'%' => '%25',
'&' => '%26',
'=' => '%3D',
]);
}
function formDecode(string $str): string {
return strtr($str, [
'%25' => '%',
'%26' => '&',
'%3D' => '=',
]);
}
// 簽名字串組裝:參數鍵值排序後拼接
$signStr = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
// PHP_QUERY_RFC3986 使用 rawurlencode,符合標準
$signature = hash_hmac('sha256', $signStr, $secretKey);
$redirectUrl = 'https://example.com/callback?' . http_build_query([
'msg' => '操作成功',
'return_url' => 'https://mysite.com/dashboard',
], '', '&', PHP_QUERY_RFC3986);
header('Location: ' . $redirectUrl);
// JS 端
const token = btoa(JSON.stringify({uid: 123, exp: Date.now() + 3600000}));
// PHP 端
$data = json_decode(base64_decode($token), true);
// 無編碼問題,因 base64 僅含 A-Z a-z 0-9 + / =
rawurlencode、JS 用 encodeURIComponent。http_build_query:指定 PHP_QUERY_RFC3986 旗標,自動處理巢狀陣列、多值參數。編碼不一致是前後端整合的常見坑。採用標準庫函數(rawurlencode/http_build_query)並統一規範,能從根源消除此類問題。自訂函數僅作為對接不可變更的舊系統之過渡方案。