chrome.debugger

Mô tả

API chrome.debugger đóng vai trò là phương thức truyền tải thay thế cho giao thức gỡ lỗi từ xa của Chrome. Sử dụng chrome.debugger để gắn vào một hoặc nhiều tab nhằm theo dõi tương tác mạng, gỡ lỗi JavaScript, thay đổi DOM và CSS, và nhiều hơn nữa. Sử dụngDebuggee tài sảntabId để nhắm mục tiêu các tab bằngsendCommand và các sự kiện định tuyến bởitabId từonEvent hàm gọi lại.

Quyền

debugger

Bạn phải khai báo quyền "debugger" trong tệp kê khai tiện ích mở rộng của mình để sử dụng API này.

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

Hạn chế chính sách doanh nghiệp

Trên các thiết bị doanh nghiệp, một số chính sách có thể hạn chế các tiện ích mở rộng gắn trình gỡ lỗi bằng mô hình "tất cả hoặc không có gì" tại thời điểm gắn (chrome.debugger.attach() ):

  • Hạn chế của máy chủ: Nếu chính sách doanh nghiệpExtensionSettings cấu hình các máy chủ bị chặn (runtime_blocked_hosts ) để mở rộng, chrome.debugger.attach() bị chặn trên tất cả các mục tiêu với lỗi"Host access is restricted by policy." (ngay cả khi nguồn gốc cá nhân nằm trongruntime_allowed_hosts ).
  • Chính sách chụp màn hình và DLP: Nếu chính sách doanh nghiệpDisableScreenshots Vô hiệu hóa tính năng chụp ảnh màn hình hoặc các quy tắc Ngăn ngừa mất dữ liệu (DLP) áp dụng cho mục tiêu.chrome.debugger.attach() thất bại với lỗi"Screenshot capture is restricted by policy." .

Khái niệm và cách sử dụng

Sau khi được gắn kết, API chrome.debugger cho phép bạn gửi các lệnh Giao thức Công cụ Phát triển Chrome (CDP) đến một mục tiêu nhất định. Việc giải thích chi tiết về CDP nằm ngoài phạm vi của tài liệu này — để tìm hiểu thêm về CDP, hãy xem tài liệu chính thức về CDP .

Mục tiêu

Các mục tiêu đại diện cho đối tượng đang được gỡ lỗi — điều này có thể bao gồm một tab, một iframe hoặc một tiến trình con. Mỗi mục tiêu được xác định bằng một UUID và có một loại liên kết (chẳng hạn như iframe, shared_worker, và nhiều loại khác).

Trong cùng một mục tiêu, có thể có nhiều ngữ cảnh thực thi khác nhau — ví dụ, các iframe cùng quy trình không có mục tiêu duy nhất mà thay vào đó được biểu diễn dưới dạng các ngữ cảnh khác nhau có thể được truy cập từ một mục tiêu duy nhất.

Các miền bị hạn chế

Vì lý do bảo mật, API chrome.debugger không cung cấp quyền truy cập vào tất cả các Miền Giao thức Chrome DevTools. Các miền khả dụng là: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Lưu trữ, Mục tiêu, Theo dõi, WebAudio và WebAuthn.

Làm việc với khung

Không có sự tương ứng một đối một giữa các khung hình và mục tiêu. Trong cùng một tab, nhiều khung quy trình giống nhau có thể chia sẻ cùng một mục tiêu nhưng sử dụng ngữ cảnh thực thi khác nhau. Mặt khác, một mục tiêu mới có thể được tạo cho iframe nằm ngoài tiến trình.

Để gắn vào tất cả các khung, bạn cần xử lý từng loại khung riêng biệt:

  • Theo dõi sự kiện Runtime.executionContextCreated để xác định các ngữ cảnh thực thi mới được liên kết với cùng một khung quy trình.

  • Làm theo các bước để đính kèm vào các mục tiêu liên quan nhằm xác định các khung hình ngoài quy trình.

Sau khi kết nối với một mục tiêu, bạn có thể muốn kết nối với các mục tiêu liên quan khác, bao gồm cả các khung con ngoài quy trình hoặc các worker được liên kết.

Kể từ Chrome 125, API chrome.debugger sẽ hỗ trợ các phiên phẳng. Thao tác này cho phép bạn thêm các mục tiêu bổ sung làm thành phần con vào phiên gỡ lỗi chính và gửi thông báo cho chúng mà không cần gọi đến chrome.debugger.attach. Thay vào đó, bạn có thể thêm thuộc tính sessionId khi gọi chrome.debugger.sendCommand để xác định mục tiêu con mà bạn muốn gửi lệnh đến.

Để tự động đính kèm vào các khung con ngoài quy trình, trước tiên, hãy thêm một trình nghe cho sự kiện 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");
  }
});

Sau đó, hãy bật tính năng tự động đính kèm bằng cách gửi lệnh Target.setAutoAttach với lựa chọn flatten được đặt thành true:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

Tính năng tự động đính kèm chỉ đính kèm vào những khung hình mà mục tiêu nhận biết được, tức là chỉ giới hạn ở những khung hình là phần tử con trực tiếp của một khung hình được liên kết với mục tiêu. Ví dụ: với hệ phân cấp khung A -> B -> C (trong đó tất cả đều là đa nguồn), việc gọi Target.setAutoAttach cho mục tiêu được liên kết với A sẽ dẫn đến việc phiên cũng được đính kèm vào B. Tuy nhiên, phương thức này không đệ quy, vì vậy, bạn cũng cần gọi Target.setAutoAttach cho B để đính kèm phiên vào C.

Ví dụ

Để dùng thử API này, hãy cài đặt ví dụ về API gỡ lỗi trong kho lưu trữ chrome-extension-samples.

Loại

Debuggee

Giá trị nhận dạng của chương trình cần gỡ lỗi. Bạn phải chỉ định tabId, extensionId hoặc targetId

Thuộc tính

  • extensionId

    chuỗi không bắt buộc

    Mã nhận dạng của tiện ích mà bạn dự định gỡ lỗi. Bạn chỉ có thể đính kèm vào trang nền của tiện ích khi dùng công tắc dòng lệnh --silent-debugger-extension-api.

  • tabId

    number không bắt buộc

    Mã nhận dạng của thẻ mà bạn dự định gỡ lỗi.

  • targetId

    chuỗi không bắt buộc

    Mã định danh ẩn của mục tiêu gỡ lỗi.

DebuggerSession

Chrome 125+

Mã định danh phiên gỡ lỗi. Một trong các giá trị tabId, extensionId hoặc targetId phải được chỉ định. Ngoài ra, bạn cũng có thể cung cấp thêm sessionId (mã định danh phiên) tùy chọn. Nếu sessionId được chỉ định cho các đối số được gửi từonEvent Điều đó có nghĩa là sự kiện đến từ một phiên giao thức con bên trong phiên gỡ lỗi gốc. Nếu sessionId được chỉ định khi truyền vàosendCommand Nó nhắm mục tiêu vào một phiên giao thức con trong phiên gỡ lỗi gốc.

Thuộc tính

  • extensionId

    chuỗi không bắt buộc

    Mã nhận dạng của tiện ích mà bạn dự định gỡ lỗi. Bạn chỉ có thể đính kèm vào trang nền của tiện ích khi dùng công tắc dòng lệnh --silent-debugger-extension-api.

  • sessionId

    chuỗi không bắt buộc

    Mã định danh không rõ ràng của phiên giao thức Chrome DevTools. Xác định một phiên con nằm trong phiên gốc được xác định bởi tabId, extensionId hoặc targetId.

  • tabId

    number không bắt buộc

    Mã nhận dạng của thẻ mà bạn dự định gỡ lỗi.

  • targetId

    chuỗi không bắt buộc

    Mã định danh ẩn của mục tiêu gỡ lỗi.

DetachReason

Chrome 44 trở lên

Lý do chấm dứt kết nối.

Enum

"target_closed"

"đã_hủy_bởi_người_dùng"

TargetInfo

Thông tin mục tiêu gỡ lỗi

Thuộc tính

  • đính kèm

    boolean

    Trả về true nếu trình gỡ lỗi đã được gắn kết.

  • extensionId

    chuỗi không bắt buộc

    Mã định danh phần mở rộng, được xác định nếu loại = 'background_page'.

  • faviconUrl

    chuỗi không bắt buộc

    URL mục tiêu của biểu tượng favicon.

  • id

    chuỗi

    Mã số mục tiêu.

  • tabId

    number không bắt buộc

    ID của tab, được định nghĩa nếu type == 'page'.

  • tiêu đề

    chuỗi

    Tiêu đề trang đích.

  • Loại mục tiêu.

  • url

    chuỗi

    URL mục tiêu.

TargetInfoType

Chrome 44 trở lên

Loại mục tiêu.

Enum

"trang"

"background_page"

"công nhân"

"khác"

Phương thức

attach()

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

Đính kèm trình gỡ lỗi vào mục tiêu đã cho.

Thông số

  • mục tiêu

    Debuggee

    Mục tiêu gỡ lỗi mà bạn muốn đính kèm.

  • requiredVersion

    chuỗi

    Phiên bản giao thức gỡ lỗi bắt buộc ("0.1"). Bạn chỉ có thể đính kèm vào chương trình gỡ lỗi có phiên bản chính trùng khớp và phiên bản phụ lớn hơn hoặc bằng. Bạn có thể xem danh sách các phiên bản giao thức tại đây.

Giá trị trả về

  • Promise<void>

    Chrome 96 trở lên

    Phân giải sau khi thao tác đính kèm thành công hoặc không thành công. Lệnh hứa này sẽ phân giải mà không có giá trị. Nếu thao tác đính kèm không thành công, thì lời hứa sẽ bị từ chối.

detach()

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

Tách trình gỡ lỗi khỏi mục tiêu đã cho.

Thông số

  • mục tiêu

    Debuggee

    Mục tiêu gỡ lỗi mà bạn muốn tách.

Giá trị trả về

  • Promise<void>

    Chrome 96 trở lên

    Sự kiện này sẽ được giải quyết sau khi thao tác tách rời thành công hoặc thất bại. Lệnh hứa này sẽ phân giải mà không có giá trị. Nếu quá trình tách rời thất bại, lời hứa sẽ bị từ chối.

getTargets()

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

Trả về danh sách các mục tiêu gỡ lỗi khả dụng.

Giá trị trả về

sendCommand()

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

Gửi lệnh đã cho đến mục tiêu gỡ lỗi.

Thông số

  • mục tiêu

    DebuggerSession

    Mục tiêu gỡ lỗi mà bạn muốn gửi lệnh đến.

  • method

    chuỗi

    Tên phương thức. Nên là một trong những phương pháp được định nghĩa bởi giao thức gỡ lỗi từ xa.

  • commandParams

    đối tượng không bắt buộc

    Đối tượng JSON chứa các tham số yêu cầu. Đối tượng này phải tuân thủ lược đồ tham số gỡ lỗi từ xa cho phương thức đã cho.

Giá trị trả về

  • Lời hứa<đối tượng | không xác định>

    Chrome 96 trở lên

    Thân bài phản hồi. Nếu xảy ra lỗi trong quá trình gửi tin nhắn, lời hứa sẽ bị từ chối.

Sự kiện

onDetach

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

Sự kiện này được kích hoạt khi trình duyệt kết thúc phiên gỡ lỗi cho tab đó. Điều này xảy ra khi tab đang được đóng hoặc khi Chrome DevTools được khởi chạy cho tab đang được đính kèm.

Thông số

onEvent

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

Sự kiện này được kích hoạt bất cứ khi nào mục tiêu gỡ lỗi phát sinh sự kiện đo lường.

Thông số

  • callback

    hàm

    Tham số callback có dạng như sau: 

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

    • method

      chuỗi

    • tham số

      đối tượng không bắt buộc