在 jQuery AJAX 開發中,error 回調是診斷請求失敗的關鍵。許多開發者僅知道 alert('錯誤'),卻忽略了三個參數 XMLHttpRequest、textStatus、errorThrown 蘊含的豐富診斷資訊。本文將系統梳理錯誤處理機制,並總結高頻錯誤場景與排查清單。
$.ajax({
url: '/api/data',
type: 'POST',
data: { id: 0 },
dataType: 'json',
success: function(msg) {
console.log('成功:', msg);
},
error: function(XMLHttpRequest, textStatus, errorThrown) {
// 核心調試區塊
},
complete: function(XMLHttpRequest, textStatus) {
// 無論成敗皆執行
}
});
jQuery 封裝的原生 XMLHttpRequest 增強版,關鍵屬性:
status:HTTP 狀態碼(200、404、500 等)readyState:請求狀態(0=未初始化, 1=載入中, 2=已載入, 3=交互中, 4=完成)responseText:原始回應文本responseJSON:解析後的 JSON(若 dataType=json 且解析成功)getAllResponseHeaders() / getResponseHeader(name):取得回應標頭| 值 | 含義 | 典型原因 |
|---|---|---|
'timeout' | 請求超時 | 伺服器無回應、timeout 設定過短 |
'error' | 一般錯誤 | HTTP 狀態碼 4xx/5xx、網路中斷 |
'abort' | 請求被中止 | 呼叫 xhr.abort()、使用者離頁 |
'parsererror' | 解析失敗 | JSON 格式錯誤、回應非預期格式(如 HTML 錯誤頁) |
'notmodified' | 資源未修改 | ifModified: true 且 304 Not Modified |
'Not Found'、'Internal Server Error')error: function(xhr, textStatus, errorThrown) {
console.group('AJAX 錯誤詳情');
console.log('URL:', this.url);
console.log('HTTP 狀態:', xhr.status);
console.log('readyState:', xhr.readyState);
console.log('textStatus:', textStatus);
console.log('errorThrown:', errorThrown);
console.log('回應標頭:', xhr.getAllResponseHeaders());
console.log('回應內容:', xhr.responseText);
console.groupEnd();
// 針對性處理
switch (textStatus) {
case 'timeout':
alert('請求超時,請檢查網路或聯繫管理員');
break;
case 'parsererror':
alert('資料格式錯誤,請聯繫後端修正 API 回應');
break;
case 'error':
if (xhr.status === 401) location.href = '/login';
else if (xhr.status >= 500) alert('伺服器內部錯誤');
break;
}
}
parsererror 且回應為空或 HTML現象:dataType: 'json' 但伺服器回傳 HTML 錯誤頁、空白、或非 JSON 字串。
排查:
Content-Type: application/json 標頭{} 或 null,而非空字串錯誤寫法:data: '' 或省略 data
正確寫法:data: {} 或 data: '{}'(確保發送有效 JSON 物件)
header('Content-Type: application/json; charset=utf-8');<meta charset="utf-8">現象:xhr.status = 0,textStatus = 'error',無回應內容。
原因:瀏覽器攔截跨域請求,伺服器未返回 Access-Control-Allow-Origin。
解決:後端配置 CORS 標頭,或使用代理/JSONP(僅 GET)。
complete: function(xhr, textStatus) {
// 恢復按鈕狀態、關閉 loading、記錄日誌
btn.prop('disabled', false).text('提交');
loading.hide();
// this 指向 $.ajax 設定物件,可取得原始 options
console.log('請求耗時:', Date.now() - this._startTime);
}
善用 error 回調的三個參數,配合瀏覽器開發者工具 Network 面板,能將 AJAX 排查效率提升 80%。記住核心原則:先看 HTTP 狀態碼,再看 textStatus 分類,最後分析回應內容。將標準調試模板納入團隊代碼規範,讓錯誤無處遁形。