PHP JSON 資料處理完整指南：編碼、解碼、跨域、實戰案例

PHP JSON 處理全攻略：從基礎語法到跨域應用、效能優化

JSON (JavaScript Object Notation) 是現代 Web 應用的核心資料交換格式。PHP 5.2+ 內建 json_encode()、json_decode()，本文系統整理編碼選項、中文處理、JavaScript 交互、跨域技巧、錯誤排查等實戰知識。

核心函數與參數

// 編碼：PHP 變數 → JSON 字串
json_encode($value, $flags = 0, $depth = 512): string|false

// 解碼：JSON 字串 → PHP 變數
json_decode($json, $assoc = false, $depth = 512, $options = 0): mixed

常用編碼旗標 (Flags)

推薦預設編碼選項

$default_flags = JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP;

$json = json_encode($data, $default_flags);

中文編碼核心原則

• PHP 檔案必須儲存為 UTF-8 無 BOM
• 資料庫連線設定 SET NAMES utf8mb4
• 輸出 Header Content-Type: application/json; charset=utf-8
• 若歷史專案為 GBK/Big5，需 iconv('GBK', 'UTF-8', $str) 轉碼後再 encode

資料結構對應關係

// PHP 關聯陣列 → JSON 物件
['id' => 1, 'name' => '張三'] → {"id":1,"name":"張三"}

// PHP 索引陣列 → JSON 陣列
['蘋果', '香蕉'] → ["蘋果","香蕉"]

// 物件屬性 → JSON 物件
class User { public $id=1; public $name='張三'; }
new User() → {"id":1,"name":"張三"}

// 多維混合
[['id'=>1], ['id'=>2]] → [{"id":1},{"id":2}]

JavaScript 端解析最佳實踐

// 現代瀏覽器 (IE10+)
const data = JSON.parse(jsonString);

// jQuery (自動處理 Content-Type)
$.getJSON('/api/users', function(data) { ... });

// Fetch API
fetch('/api/users')
  .then(r => r.json())
  .then(data => console.log(data));

// 避免使用 eval() - 極大安全風險

JSONP 跨域實作 (傳統方案)

伺服端 callback.php：

<?php
header('Content-Type: application/javascript; charset=utf-8');
$data = ['name' => '張三', 'time' => time()];
$callback = $_GET['callback'] ?? 'callback';
// 安全驗證 callback 只含字母數字底線
if (!preg_match('/^[\w.]+$/', $callback)) exit('Invalid callback');
echo "$callback(" . json_encode($data, JSON_UNESCAPED_UNICODE) . ");";

客戶端：

<script>
function handleUser(data) { console.log(data.name); }
</script>
<script src="callback.php?callback=handleUser"></script>

現代跨域方案：CORS (推薦)

<?php
// API 端統一加入
header('Access-Control-Allow-Origin: https://your-frontend.com'); // 或 * (非帶憑證)
header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type, Authorization');
header('Access-Control-Allow-Credentials: true');

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(204);
    exit;
}

錯誤處理與除錯

$json = json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
// PHP 7.3+ 失敗拋出 JsonException

// 手動檢查 (舊版相容)
$json = json_encode($data);
if (json_last_error() !== JSON_ERROR_NONE) {
    error_log('JSON 編碼失敗: ' . json_last_error_msg());
    // 降級處理：移除問題資料、記錄、回傳錯誤格式
}

效能優化建議

• 大量資料分頁輸出，避免單次編碼超大字串
• API 回傳啟用 JSON_UNESCAPED_UNICODE 減少體積 (中文不轉義)
• 高頻 API 使用 igbinary、msgpack 二進位序列化替代 JSON
• Nginx 啟用 gzip、brotli 壓縮 JSON 回應

線上工具輔助開發

• JSON 格式化/壓縮：在線工具
• XML ⇄ JSON 轉換：互轉工具
• PHP 代碼美化：格式化工具

掌握 JSON 編解碼細節、跨域方案選型、錯誤處理模式，能讓前後端協作更順暢、API 更穩健高效。