chrome.debugger

คำอธิบาย

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 (CDP) ไปยังเป้าหมายที่ต้องการได้ การอธิบาย CDP อย่างละเอียดอยู่นอกขอบเขต ของเอกสารประกอบนี้ หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับ CDP โปรดดูเอกสารประกอบ CDP อย่างเป็นทางการ

เป้าหมาย

เป้าหมายแสดงถึงสิ่งที่กำลังดีบัก ซึ่งอาจรวมถึงแท็บ iframe หรือ Worker เป้าหมายแต่ละรายการจะระบุด้วย UUID และมีประเภทที่เชื่อมโยง (เช่น iframe, shared_worker และอื่นๆ)

ภายในเป้าหมายอาจมีบริบทการดำเนินการหลายอย่าง เช่น iframe ในกระบวนการเดียวกันจะไม่ได้รับเป้าหมายที่ไม่ซ้ำกัน แต่จะแสดงเป็นบริบทที่แตกต่างกันแทน ซึ่งเข้าถึงได้จากเป้าหมายเดียว

โดเมนที่ถูกจำกัด

chrome.debugger API ไม่ได้ให้สิทธิ์เข้าถึงโดเมนโปรโตคอลทั้งหมดของเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome เนื่องด้วยเหตุผลด้านความปลอดภัย โดเมนที่ใช้ได้ ได้แก่ Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio และ WebAuthn

ทำงานกับเฟรม

ไม่มีการแมปเฟรมกับเป้าหมายแบบหนึ่งต่อหนึ่ง ภายในแท็บเดียว เฟรมกระบวนการเดียวกันหลายเฟรมอาจใช้เป้าหมายเดียวกัน แต่ใช้บริบทการดำเนินการที่แตกต่างกัน ในทางกลับกัน อาจมีการสร้างเป้าหมายใหม่สำหรับ iframe ที่อยู่นอกกระบวนการ

หากต้องการแนบกับทุกเฟรม คุณต้องจัดการเฟรมแต่ละประเภทแยกกัน ดังนี้

• รอรับเหตุการณ์ Runtime.executionContextCreated เพื่อระบุบริบทการดำเนินการใหม่ ที่เชื่อมโยงกับเฟรมกระบวนการเดียวกัน

• ทําตามขั้นตอนเพื่อแนบกับเป้าหมายที่เกี่ยวข้องเพื่อ ระบุเฟรมที่อยู่นอกกระบวนการ

แนบกับเป้าหมายที่เกี่ยวข้อง

หลังจากเชื่อมต่อกับเป้าหมายแล้ว คุณอาจต้องการเชื่อมต่อกับเป้าหมายที่เกี่ยวข้องอื่นๆ รวมถึงเฟรมย่อยที่อยู่นอกกระบวนการหรือ Worker ที่เชื่อมโยง

ตั้งแต่ Chrome 125 เป็นต้นไป chrome.debugger API จะรองรับเซสชันแบบเรียบ ซึ่งจะช่วยให้คุณเพิ่มเป้าหมายอื่นๆ เป็นอุปกรณ์ย่อยลงในเซสชันการแก้ไขข้อบกพร่องหลักและส่งข้อความถึงเป้าหมายเหล่านั้นได้โดยไม่ต้องเรียกใช้ 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 }]
});

การแนบอัตโนมัติจะแนบกับเฟรมที่เป้าหมายรับรู้เท่านั้น ซึ่งจำกัดไว้ที่เฟรมที่เป็นเฟรมย่อยที่อยู่ใต้เฟรมที่เชื่อมโยงกับเฟรมนั้นโดยตรง ตัวอย่างเช่น เมื่อมีลำดับชั้นของเฟรมเป็น A -> B -> C (ซึ่งทั้งหมดเป็นแบบข้ามต้นทาง) การเรียกใช้ Target.setAutoAttach สำหรับเป้าหมายที่เชื่อมโยงกับ A จะส่งผลให้ เซสชันเชื่อมโยงกับ B ด้วย อย่างไรก็ตาม การดำเนินการนี้ไม่ใช่แบบเรียกซ้ำ ดังนั้นจึงต้องเรียกใช้ Target.setAutoAttach สำหรับ B ด้วยเพื่อให้แนบเซสชันกับ C

ตัวอย่าง

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง API ของดีบักเกอร์จากที่เก็บchrome-extension-samples

ประเภท

Debuggee

ตัวระบุ Debuggee ต้องระบุ tabId, extensionId หรือ targetId

พร็อพเพอร์ตี้

• extensionId

  สตริง ไม่บังคับ

  รหัสของส่วนขยายที่คุณต้องการแก้ไขข้อบกพร่อง การแนบกับหน้าพื้นหลังของส่วนขยายจะทำได้เฉพาะเมื่อใช้สวิตช์บรรทัดคำสั่ง --silent-debugger-extension-api เท่านั้น

• tabId

  หมายเลข ไม่บังคับ

  รหัสของแท็บที่คุณต้องการแก้ไขข้อบกพร่อง

• targetId

  สตริง ไม่บังคับ

  รหัสที่ไม่โปร่งใสของเป้าหมายการแก้ไขข้อบกพร่อง

DebuggerSession

Chrome 125 ขึ้นไป

ตัวระบุเซสชันของดีบักเกอร์ ต้องระบุ tabId, extensionId หรือ targetId อย่างใดอย่างหนึ่ง นอกจากนี้ คุณยังระบุ sessionId ที่ไม่บังคับได้ด้วย หากมีการระบุ sessionId สำหรับอาร์กิวเมนต์ที่ส่งจาก onEvent แสดงว่าเหตุการณ์มาจากเซสชันโปรโตคอลย่อยภายในเซสชันการแก้ไขข้อบกพร่องรูท หากมีการระบุ sessionId เมื่อส่งไปยัง sendCommand ระบบจะกำหนดเป้าหมายเซสชันโปรโตคอลย่อยภายในเซสชันการแก้ไขข้อบกพร่องรูท

พร็อพเพอร์ตี้

• extensionId

  สตริง ไม่บังคับ

  รหัสของส่วนขยายที่คุณต้องการแก้ไขข้อบกพร่อง การแนบกับหน้าพื้นหลังของส่วนขยายจะทำได้ก็ต่อเมื่อใช้สวิตช์บรรทัดคำสั่ง --silent-debugger-extension-api เท่านั้น

• sessionId

  สตริง ไม่บังคับ

  รหัสที่ทึบแสงของเซสชันโปรโตคอลเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome ระบุเซสชันย่อยภายในเซสชันรูทที่ระบุโดย tabId, extensionId หรือ targetId

• tabId

  หมายเลข ไม่บังคับ

  รหัสของแท็บที่คุณต้องการแก้ไขข้อบกพร่อง

• targetId

  สตริง ไม่บังคับ

  รหัสที่ไม่โปร่งใสของเป้าหมายการแก้ไขข้อบกพร่อง

DetachReason

Chrome 44 ขึ้นไป

เหตุผลของการสิ้นสุดการเชื่อมต่อ

ค่าแจกแจง

"target_closed"

"canceled_by_user"

TargetInfo

ข้อมูลเป้าหมายการแก้ไขข้อบกพร่อง

พร็อพเพอร์ตี้

• เชื่อมต่อแล้ว

  บูลีน

  จริงหากดีบักเกอร์แนบอยู่แล้ว

• extensionId

  สตริง ไม่บังคับ

  รหัสส่วนขยายที่กำหนดไว้หาก type = 'background_page'

• faviconUrl

  สตริง ไม่บังคับ

  URL ของไอคอน Fav เป้าหมาย

• id

  สตริง

  รหัสเป้าหมาย

• tabId

  หมายเลข ไม่บังคับ

  รหัสแท็บที่กำหนดไว้หาก type == 'page'

• title

  สตริง

  ชื่อหน้าเป้าหมาย

• ประเภท

  TargetInfoType

  ประเภทเป้าหมาย

• URL

  สตริง

  URL เป้าหมาย

TargetInfoType

Chrome 44 ขึ้นไป

ประเภทเป้าหมาย

ค่าแจกแจง

"page"

"background_page"

"worker"

"อื่นๆ"

เมธอด

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

แนบดีบักเกอร์กับเป้าหมายที่ระบุ

พารามิเตอร์

• เป้าหมาย

  โปรแกรมที่กำลังแก้ไขข้อบกพร่อง

  เป้าหมายการแก้ไขข้อบกพร่องที่คุณต้องการแนบ

• requiredVersion

  สตริง

  เวอร์ชันโปรโตคอลการแก้ไขข้อบกพร่องที่จำเป็น ("0.1") โดยจะแนบได้เฉพาะกับโปรแกรมที่ต้องการแก้ไขข้อบกพร่องที่มีเวอร์ชันหลักตรงกันและเวอร์ชันย่อยมากกว่าหรือเท่ากันเท่านั้น ดูรายการเวอร์ชันโปรโตคอลได้ที่นี่

การคืนสินค้า

• Promise<void>

  Chrome 96 ขึ้นไป

  จะแก้ไขเมื่อการดำเนินการแนบสำเร็จหรือไม่สำเร็จ Promise จะได้รับการแก้ไขโดยไม่มีค่า หากการแนบไม่สำเร็จ ระบบจะปฏิเสธสัญญา

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

ยกเลิกการเชื่อมต่อดีบักเกอร์จากเป้าหมายที่ระบุ

พารามิเตอร์

• เป้าหมาย

  โปรแกรมที่กำลังแก้ไขข้อบกพร่อง

  เป้าหมายการแก้ไขข้อบกพร่องที่คุณต้องการยกเลิกการเชื่อมต่อ

การคืนสินค้า

• Promise<void>

  Chrome 96 ขึ้นไป

  จะแก้ไขเมื่อการดำเนินการยกเลิกการเชื่อมต่อสำเร็จหรือไม่สำเร็จ Promise จะได้รับการแก้ไขโดยไม่มีค่า หากการแยกไม่สำเร็จ ระบบจะปฏิเสธสัญญา

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

แสดงรายการเป้าหมายการแก้ไขข้อบกพร่องที่ใช้ได้

การคืนสินค้า

• Promise<TargetInfo[]>

  Chrome 96 ขึ้นไป

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

ส่งคำสั่งที่ระบุไปยังเป้าหมายการแก้ไขข้อบกพร่อง

พารามิเตอร์

• เป้าหมาย

  DebuggerSession

  เป้าหมายการแก้ไขข้อบกพร่องที่คุณต้องการส่งคำสั่ง

• method

  สตริง

  ชื่อเมธอด ควรเป็นวิธีใดวิธีหนึ่งที่กำหนดโดยโปรโตคอลการแก้ไขข้อบกพร่องจากระยะไกล

• commandParams

  ออบเจ็กต์ ไม่บังคับ

  ออบเจ็กต์ JSON ที่มีพารามิเตอร์คำขอ ออบเจ็กต์นี้ต้องเป็นไปตามรูปแบบพารามิเตอร์การแก้ไขข้อบกพร่องจากระยะไกลสำหรับเมธอดที่ระบุ

การคืนสินค้า

• Promise<object | undefined>

  Chrome 96 ขึ้นไป

  เนื้อหาการตอบกลับ หากเกิดข้อผิดพลาดขณะโพสต์ข้อความ ระบบจะปฏิเสธ Promise

กิจกรรม

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

เริ่มทำงานเมื่อเบราว์เซอร์สิ้นสุดเซสชันการแก้ไขข้อบกพร่องสำหรับแท็บ กรณีนี้จะเกิดขึ้นเมื่อมีการปิดแท็บหรือเรียกใช้ Chrome DevTools สำหรับแท็บที่แนบ

พารามิเตอร์

• callback

  ฟังก์ชัน

  พารามิเตอร์ callback มีลักษณะดังนี้

  (source: Debuggee, reason: DetachReason) => void

  • source

    โปรแกรมที่กำลังแก้ไขข้อบกพร่อง

  • เหตุผล

    DetachReason

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

เริ่มทำงานทุกครั้งที่เกิดเหตุการณ์การวัดผลปัญหาเป้าหมายการแก้ไขข้อบกพร่อง

พารามิเตอร์

• callback

  ฟังก์ชัน

  พารามิเตอร์ callback มีลักษณะดังนี้

  (source: DebuggerSession, method: string, params?: object) => void

  • source

    DebuggerSession

  • method

    สตริง

  • พารามิเตอร์

    ออบเจ็กต์ ไม่บังคับ