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 DevTools ทั้งหมดเนื่องด้วยเหตุผลด้านความปลอดภัย โดเมนที่ใช้ได้ ได้แก่ 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 ขึ้นไป

detach()

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

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

พารามิเตอร์

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

  • Promise<void>

    Chrome 96 ขึ้นไป

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

    object ไม่บังคับ

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

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

  • Promise<object | undefined>

    Chrome 96 ขึ้นไป

กิจกรรม

onDetach

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

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

พารามิเตอร์

onEvent

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

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

    • method

      สตริง

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

      object ไม่บังคับ