คำอธิบาย
chrome.debugger
API ทำหน้าที่เป็นการส่งสำรองสำหรับโปรโตคอลการแก้ไขข้อบกพร่องระยะไกลของ Chrome ใช้ chrome.debugger
เพื่อแนบกับแท็บอย่างน้อย 1 แท็บเพื่อควบคุมการโต้ตอบของเครือข่าย, แก้ไขข้อบกพร่องของ JavaScript, เปลี่ยนแปลง DOM และ CSS และอื่นๆ ใช้คุณสมบัติ Debuggee
tabId
เพื่อกำหนดเป้าหมายแท็บด้วย sendCommand
และกำหนดเส้นทางเหตุการณ์ตาม tabId
จากโค้ดเรียกกลับ onEvent
สิทธิ์
debugger
คุณต้องประกาศสิทธิ์ "debugger"
ในไฟล์ Manifest ของส่วนขยายเพื่อใช้ API นี้
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
แนวคิดและการใช้งาน
เมื่อแนบแล้ว chrome.debugger
API จะช่วยให้คุณส่งคำสั่ง Chrome DevTools Protocol
(CDP) ไปยังเป้าหมายที่กำหนดได้ การอธิบาย CDP แบบเจาะลึกอยู่นอกเหนือขอบเขตของเอกสารนี้ หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับ CDP ในเอกสาร CDP อย่างเป็นทางการ
เป้าหมาย
เป้าหมายแสดงถึงสิ่งที่กำลังแก้ไขข้อบกพร่อง ซึ่งอาจรวมถึงแท็บ, iframe หรือผู้ปฏิบัติงาน เป้าหมายแต่ละรายการจะระบุโดย UUID และมีประเภทที่เกี่ยวข้อง (เช่น iframe
, shared_worker
และอื่นๆ)
ภายในเป้าหมายหนึ่งอาจมีบริบทการดำเนินการหลายรายการ เช่น iframe ของกระบวนการเดียวกันจะไม่ได้รับเป้าหมายที่ไม่ซ้ำกัน แต่แสดงเป็นบริบทที่แตกต่างกันซึ่งเข้าถึงได้จากเป้าหมายเดียว
โดเมนที่ถูกจำกัด
ด้วยเหตุผลด้านความปลอดภัย chrome.debugger
API ไม่ได้ให้สิทธิ์เข้าถึงโดเมนโปรโตคอลสำหรับนักพัฒนาเว็บใน Chrome ทั้งหมด โดเมนที่มีอยู่ได้แก่ การช่วยเหลือพิเศษ,
การตรวจสอบ, CacheStorage, คอนโซล,
CSS, ฐานข้อมูล, โปรแกรมแก้ไขข้อบกพร่อง, DOM,
DOMDebugger, DOMSnapshotWebAudioWebAuthn
ใช้งานกรอบรูป
ไม่มีการแมปเฟรมกับเป้าหมายแบบ 1 ต่อ 1 ภายในแท็บเดียว เฟรมกระบวนการเดียวกันหลายเฟรมอาจใช้เป้าหมายเดียวกัน แต่ใช้บริบทการดำเนินการต่างกัน ในทางกลับกัน ระบบอาจสร้างเป้าหมายใหม่สำหรับ iframe นอกกระบวนการ
หากต้องการแนบกับเฟรมทั้งหมด คุณต้องจัดการเฟรมแต่ละประเภทแยกกัน ดังนี้
ฟังเหตุการณ์
Runtime.executionContextCreated
เพื่อระบุบริบทการดำเนินการใหม่ที่เชื่อมโยงกับเฟรมของกระบวนการเดียวกันทำตามขั้นตอนเพื่อแนบกับเป้าหมายที่เกี่ยวข้องเพื่อระบุเฟรมนอกกระบวนการ
แนบกับเป้าหมายที่เกี่ยวข้อง
หลังจากเชื่อมต่อกับเป้าหมายแล้ว คุณอาจต้องเชื่อมต่อกับเป้าหมายที่เกี่ยวข้องเพิ่มเติม ซึ่งรวมถึงเฟรมย่อยหรือผู้ปฏิบัติงานที่เกี่ยวข้องนอกกระบวนการ
ตั้งแต่ Chrome 125 เป็นต้นไป API ของ chrome.debugger
จะรองรับเซสชันแบบคงที่ ซึ่งจะช่วยให้คุณเพิ่มเป้าหมายเพิ่มเติมเป็นเด็กในเซสชันโปรแกรมแก้ไขข้อบกพร่องหลัก และส่งข้อความถึงกลุ่มเป้าหมายดังกล่าวได้โดยไม่ต้องเรียกใช้ chrome.debugger.attach
อีก แต่คุณสามารถเพิ่มพร็อพเพอร์ตี้ sessionId
เมื่อเรียกใช้ chrome.debugger.sendCommand
เพื่อระบุเป้าหมายย่อยที่คุณต้องการส่งคำสั่งไปให้แทนได้
หากต้องการแนบกับเฟรมย่อยที่อยู่นอกกระบวนการโดยอัตโนมัติ ให้เพิ่ม Listener สำหรับเหตุการณ์ Target.attachedToTarget
ก่อน โดยทำดังนี้
chrome.debugger.onEvent.addListener((source, method, params) => {
if (method === "Target.attachedToTarget") {
// `source` identifies the parent session, but we need to construct a new
// identifier for the child session
const session = { ...source, sessionId: params.sessionId };
// Call any needed CDP commands for the child session
await chrome.debugger.sendCommand(session, "Runtime.enable");
}
});
จากนั้นเปิดใช้แนบอัตโนมัติโดยการส่งคำสั่ง Target.setAutoAttach
พร้อมตัวเลือก flatten
ที่ตั้งค่าเป็น true
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
ตัวอย่าง
หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง API โปรแกรมแก้ไขข้อบกพร่องจากที่เก็บ chrome-extension-sample
ประเภท
Debuggee
ตัวระบุ Debuggee ต้องระบุ TabId, extensionsId หรือ targetId
พร็อพเพอร์ตี้
-
extensionId
string ไม่บังคับ
รหัสของส่วนขยายที่คุณต้องการแก้ไขข้อบกพร่อง คุณสามารถแนบหน้าพื้นหลังของส่วนขยายได้ต่อเมื่อใช้สวิตช์บรรทัดคำสั่ง
--silent-debugger-extension-api
เท่านั้น -
tabId
ตัวเลข ไม่บังคับ
รหัสของแท็บที่คุณต้องการแก้ไขข้อบกพร่อง
-
targetId
string ไม่บังคับ
รหัสทึบแสงของเป้าหมายการแก้ไขข้อบกพร่อง
DebuggerSession
ตัวระบุเซสชันโปรแกรมแก้ไขข้อบกพร่อง ต้องระบุ TabId, extensionsId หรือ targetId อย่างน้อย 1 รายการ นอกจากนี้ คุณยังระบุ sessionId ที่ไม่บังคับได้ด้วย หากระบุ sessionId สำหรับอาร์กิวเมนต์ที่ส่งจาก onEvent
หมายความว่าเหตุการณ์นั้นมาจากเซสชันโปรโตคอลย่อยภายในเซสชัน Debuggee ระดับรูท หากระบุ sessionId ไว้เมื่อส่งไปยัง sendCommand
ระบบจะกำหนดเป้าหมายเซสชันโปรโตคอลย่อยภายในเซสชัน Debuggee ระดับรูท
พร็อพเพอร์ตี้
-
extensionId
string ไม่บังคับ
รหัสของส่วนขยายที่คุณต้องการแก้ไขข้อบกพร่อง คุณสามารถแนบหน้าพื้นหลังของส่วนขยายได้ต่อเมื่อใช้สวิตช์บรรทัดคำสั่ง
--silent-debugger-extension-api
เท่านั้น -
sessionId
string ไม่บังคับ
รหัสไม่ชัดเจนของเซสชันโปรโตคอลเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome ระบุเซสชันย่อยภายในเซสชันรูทที่ระบุโดย TabId, extensionsId หรือ targetId
-
tabId
ตัวเลข ไม่บังคับ
รหัสของแท็บที่คุณต้องการแก้ไขข้อบกพร่อง
-
targetId
string ไม่บังคับ
รหัสทึบแสงของเป้าหมายการแก้ไขข้อบกพร่อง
DetachReason
เหตุผลของการสิ้นสุดการเชื่อมต่อ
ค่าแจกแจง
"target_closed"
TargetInfo
แก้ไขข้อบกพร่องของข้อมูลเป้าหมาย
พร็อพเพอร์ตี้
-
เชื่อมต่อแล้ว
boolean
เป็นจริงหากแนบโปรแกรมแก้ไขข้อบกพร่องไว้แล้ว
-
extensionId
string ไม่บังคับ
รหัสส่วนขยายที่กำหนดหากประเภท = 'background_page'
-
faviconUrl
string ไม่บังคับ
URL ของไอคอน Fav เป้าหมาย
-
id
string
รหัสเป้าหมาย
-
tabId
ตัวเลข ไม่บังคับ
รหัสแท็บที่กำหนดหากประเภท == 'page'
-
title
string
ชื่อหน้าเป้าหมาย
-
ประเภท
ประเภทเป้าหมาย
-
url
string
URL เป้าหมาย
TargetInfoType
ประเภทเป้าหมาย
ค่าแจกแจง
"background_page"
วิธีการ
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
แนบโปรแกรมแก้ไขข้อบกพร่องกับเป้าหมายที่ระบุ
พารามิเตอร์
-
เป้าหมาย
การดีบักเป้าหมายที่คุณต้องการแนบ
-
requiredVersion
string
เวอร์ชันโปรโตคอลการแก้ไขข้อบกพร่องที่จำเป็น ("0.1") ไฟล์ 1 รายการจะแนบได้กับ Debuggee ที่มีเวอร์ชันหลักที่ตรงกันและเวอร์ชันย่อยมากกว่าหรือเท่ากับเท่านั้น ดูรายการเวอร์ชันของโปรโตคอลได้ที่นี่
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 96 ขึ้นไปManifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
ปลดโปรแกรมแก้ไขข้อบกพร่องออกจากเป้าหมายที่ระบุ
พารามิเตอร์
-
เป้าหมาย
การแก้ไขข้อบกพร่องเป้าหมายที่ต้องการปลดออก
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 96 ขึ้นไปManifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
แสดงรายการเป้าหมายการแก้ไขข้อบกพร่องที่ใช้ได้
พารามิเตอร์
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(result: TargetInfo[]) => void
-
ผลลัพธ์
อาร์เรย์ของออบเจ็กต์ TargetInfo ที่สอดคล้องกับเป้าหมายการแก้ไขข้อบกพร่องที่มีอยู่
-
การคืนสินค้า
-
Promise<TargetInfo[]>
Chrome 96 ขึ้นไปManifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
ส่งคำสั่งที่ได้รับไปยังเป้าหมายการแก้ไขข้อบกพร่อง
พารามิเตอร์
-
เป้าหมาย
กำลังแก้ไขข้อบกพร่องเป้าหมายที่คุณต้องการส่งคำสั่ง
-
method
string
ชื่อเมธอด ควรเป็นวิธีการหนึ่งที่กำหนดโดยโปรโตคอลการแก้ไขข้อบกพร่องระยะไกล
-
commandParams
ออบเจ็กต์ ไม่บังคับ
ออบเจ็กต์ JSON ที่มีพารามิเตอร์คำขอ ออบเจ็กต์นี้ต้องเป็นไปตามรูปแบบพารามิเตอร์การแก้ไขข้อบกพร่องระยะไกลสำหรับเมธอดที่ระบุ
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(result?: object) => void
-
ผลลัพธ์
ออบเจ็กต์ ไม่บังคับ
ออบเจ็กต์ JSON ที่มีการตอบกลับ โครงสร้างของการตอบกลับจะแตกต่างกันไป ขึ้นอยู่กับชื่อเมธอด และกำหนดโดยแอตทริบิวต์ "returns" ของคำอธิบายคำสั่งในโปรโตคอลการแก้ไขข้อบกพร่องจากระยะไกล
-
การคืนสินค้า
-
Promise<object | undefined>
Chrome 96 ขึ้นไปManifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ
เหตุการณ์
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
เริ่มทำงานเมื่อเบราว์เซอร์สิ้นสุดเซสชันการแก้ไขข้อบกพร่องสำหรับแท็บ ซึ่งจะเกิดขึ้นเมื่อปิดแท็บหรือเรียกใช้เครื่องมือสำหรับนักพัฒนาเว็บใน Chrome ของแท็บที่แนบ
พารามิเตอร์
-
Callback
ฟังก์ชัน
พารามิเตอร์
callback
มีลักษณะดังนี้(source: Debuggee, reason: DetachReason) => void
-
source
-
สาเหตุ
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
เริ่มทำงานเมื่อใดก็ตามที่มีการแก้ไขข้อบกพร่องเหตุการณ์การวัดคุมของปัญหาเป้าหมาย
พารามิเตอร์
-
Callback
ฟังก์ชัน
พารามิเตอร์
callback
มีลักษณะดังนี้(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
string
-
params
ออบเจ็กต์ ไม่บังคับ
-