browser.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",
  ],
  ...
}

ข้อจำกัดด้านนโยบายขององค์กร

ในอุปกรณ์ขององค์กร นโยบายบางอย่างอาจจำกัดไม่ให้ส่วนขยายแนบดีบักเกอร์โดยใช้โมเดลแบบทั้งหมดหรือไม่มีเลยในเวลาที่แนบ (browser.debugger.attach())

  • ข้อจำกัดของโฮสต์: หากนโยบายระดับองค์กร ExtensionSettings กำหนดค่าโฮสต์ที่ถูกบล็อก (runtime_blocked_hosts) สำหรับส่วนขยาย ระบบจะบล็อก browser.debugger.attach() ในเป้าหมายทั้งหมดโดยมีข้อผิดพลาด "Host access is restricted by policy." (แม้ว่าต้นทางแต่ละรายการจะอยู่ใน runtime_allowed_hosts ก็ตาม)
  • นโยบายภาพหน้าจอและ DLP: หากนโยบายขององค์กร DisableScreenshots ปิดใช้การจับภาพหน้าจอหรือกฎการป้องกันข้อมูลรั่วไหล (DLP) มีผลกับเป้าหมาย browser.debugger.attach() จะล้มเหลวพร้อมข้อผิดพลาด "Screenshot capture is restricted by policy."

แนวคิดและการใช้งาน

เมื่อแนบแล้ว browser.debugger API จะช่วยให้คุณส่งคำสั่งโปรโตคอลเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome (CDP) ไปยังเป้าหมายที่กำหนดได้ การอธิบาย CDP อย่างละเอียดอยู่นอกขอบเขตของเอกสารนี้ หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับ CDP โปรดดูเอกสารประกอบอย่างเป็นทางการของ CDP

เป้าหมาย

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

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

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

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

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

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

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

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

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

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

ตั้งแต่ Chrome 125 เป็นต้นไป browser.debugger API จะรองรับเซสชันแบบแบน ซึ่งจะช่วยให้คุณเพิ่มเป้าหมายเพิ่มเติมเป็นรายการย่อยในเซสชันดีบักเกอร์หลักและ ส่งข้อความถึงเป้าหมายเหล่านั้นได้โดยไม่ต้องโทรหา browser.debugger.attach อีก แต่คุณสามารถเพิ่มพร็อพเพอร์ตี้ sessionId เมื่อเรียกใช้ browser.debugger.sendCommand เพื่อ ระบุเป้าหมายย่อยที่คุณต้องการส่งคำสั่งได้

หากต้องการแนบเฟรมย่อยที่อยู่นอกกระบวนการโดยอัตโนมัติ ให้เพิ่ม Listener สำหรับ เหตุการณ์ Target.attachedToTarget ก่อน

browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
  }
});

จากนั้นเปิดใช้แนบอัตโนมัติโดยส่งคำสั่ง Target.setAutoAttach พร้อมตัวเลือก flatten ที่ตั้งค่าเป็น true ดังนี้

await browser.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

ตัวระบุโปรแกรมที่กำลังแก้ไขข้อบกพร่อง ต้องระบุ 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 สำหรับแท็บที่แนบ

พารามิเตอร์

onEvent

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

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

    • method

      สตริง

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

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