browser.debugger

คำอธิบาย

chrome.debugger API ทำหน้าที่เป็นตัวส่งข้อมูลสำรองสำหรับโปรโตคอลการแก้ไขข้อบกพร่องระยะไกลของ Chrome ใช้ chrome.debugger เพื่อแนบกับแท็บอย่างน้อย 1 แท็บเพื่อวัดการโต้ตอบของเครือข่าย แก้ไขข้อบกพร่องของ JavaScript, เปลี่ยนแปลง DOM และ CSS และอื่นๆ ใช้พร็อพเพอร์ตี้ Debuggee tabId เพื่อกำหนดเป้าหมายแท็บด้วย sendCommand และกำหนดเส้นทางเหตุการณ์ตาม tabId จาก Callback 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 หรือเวิร์กเกอร์ เป้าหมายแต่ละรายการจะระบุด้วย UUID และมีประเภทที่เกี่ยวข้อง (เช่น iframe, shared_worker และอื่นๆ)

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

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

ด้วยเหตุผลด้านความปลอดภัย API browser.debugger จึงไม่ให้สิทธิ์เข้าถึงโดเมนโปรโตคอลเครื่องมือสำหรับนักพัฒนาเว็บใน 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

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

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

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

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

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

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

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

ตั้งแต่ 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

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

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

• extensionId

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

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

• tabId

  number ไม่บังคับ

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

• targetId

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

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

DebuggerSession

Chrome 125 ขึ้นไป เบราว์เซอร์* ตั้งแต่ Chrome 148

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

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

• extensionId

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

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

• sessionId

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

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

• tabId

  number ไม่บังคับ

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

• targetId

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

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

DetachReason

Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

ค่าแจกแจง

"target_closed"

"canceled_by_user"

TargetInfo

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

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

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

  บูลีน

  เป็นจริงหากแนบโปรแกรมแก้ไขข้อบกพร่องแล้ว

• extensionId

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

  รหัสส่วนขยายที่กำหนดไว้หากประเภท = "background_page"

• faviconUrl

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

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

• id

  สตริง

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

• tabId

  number ไม่บังคับ

  รหัสแท็บ ซึ่งกำหนดไว้หากประเภท == 'page'

• title

  สตริง

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

• ประเภท

  TargetInfoType

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

• URL

  สตริง

  URL เป้าหมาย

TargetInfoType

Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

ค่าแจกแจง

"page"

"background_page"

"worker"

"other"

เมธอด

attach()

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

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

พารามิเตอร์

• เป้าหมาย

  Debuggee

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

• requiredVersion

  สตริง

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

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

• Promise<void>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

detach()

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

แยกโปรแกรมแก้ไขข้อบกพร่องออกจากเป้าหมายที่ระบุ

พารามิเตอร์

• เป้าหมาย

  Debuggee

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

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

• Promise<void>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

getTargets()

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

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

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

• Promise<TargetInfo[]>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

sendCommand()

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

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

พารามิเตอร์

• เป้าหมาย

  DebuggerSession

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

• method

  สตริง

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

• commandParams

  object ไม่บังคับ

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

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

• Promise<object | undefined>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

กิจกรรม

onDetach

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

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

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

  • source

    Debuggee

  • เหตุผล

    DetachReason

onEvent

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

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

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

  • source

    DebuggerSession

  • method

    สตริง

  • params

    object ไม่บังคับ