Chrome hiện hỗ trợ không gian tên browser.* được chuẩn hoá (có từ Chrome 148). Chúng tôi đang dần cập nhật tài liệu. Hãy đọc thêm trong hướng dẫn chuyển đổi của chúng tôi.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

browser.debugger

Mô tả

API chrome.debugger đóng vai trò là một 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 để đính kèm vào một hoặc nhiều thẻ nhằm đo lường hoạt động tương tác mạng, gỡ lỗi JavaScript, thay đổi DOM và CSS, v.v. Sử dụng thuộc tính Debuggee tabId để nhắm đến các thẻ bằng sendCommand và định tuyến sự kiện theo tabId từ lệnh gọi lại onEvent.

Quyền

debugger

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

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

Các quy định hạn chế theo chính sách của 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ế tiện ích đính kèm trình gỡ lỗi bằng cách sử dụng mô hình tất cả hoặc không có gì tại thời điểm đính kèm (browser.debugger.attach()):

Các quy định hạn chế của máy chủ lưu trữ: Nếu chính sách doanh nghiệp ExtensionSettings định cấu hình máy chủ lưu trữ bị chặn (runtime_blocked_hosts) cho một tiện ích, thì browser.debugger.attach() sẽ bị chặn trên tất cả các mục tiêu kèm theo lỗi "Host access is restricted by policy." (ngay cả khi các nguồn gốc riêng lẻ nằm trong runtime_allowed_hosts).
Chính sách về ảnh chụp màn hình và DLP: Nếu chính sách doanh nghiệp DisableScreenshots tắt tính năng chụp ảnh màn hình hoặc các quy tắc Ngăn chặn mất dữ liệu (DLP) áp dụng cho mục tiêu, thì browser.debugger.attach() sẽ không thành công và báo lỗi "Screenshot capture is restricted by policy.".

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

Sau khi đính kèm, API browser.debugger cho phép bạn gửi các lệnh Giao thức Chrome DevTools (CDP) đến một mục tiêu nhất định. Tài liệu này không giải thích chi tiết về CDP. Để 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

Mục tiêu đại diện cho một đối tượng đang được gỡ lỗi, có thể bao gồm một thẻ, một iframe hoặc một worker. 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.v.).

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

Miền bị hạn chế

Vì lý do bảo mật, API browser.debugger không cung cấp quyền truy cập vào tất cả miền của Giao thức Chrome DevTools. Các miền hiện có là: Hỗ trợ tiếp cận, Kiểm tra, CacheStorage, Bảng điều khiển, CSS, Cơ sở dữ liệu, Trình gỡ lỗi, DOM, DOMDebugger, DOMSnapshot, Mô phỏng, Tìm nạp, IO, Đầu vào, Trình kiểm tra, Nhật ký, Mạng, Lớp phủ, Trang, Hiệu suất, Thời gian chạy, Bộ nhớ, Mục tiêu, Theo dõi, WebAudio và WebAuthn.

Làm việc với khung hình

Không có mối liên kết một-một giữa khung hình và mục tiêu. Trong một thẻ, nhiều khung cùng quy trình có thể có cùng một mục tiêu nhưng sử dụng bối 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 một iframe ngoài quy trình.

Để đính kèm vào tất cả khung hình, bạn cần xử lý riêng từng loại khung hình:

Lắng nghe sự kiện Runtime.executionContextCreated để xác định bối cảnh thực thi mới 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 ngoài quy trình.

Đính kèm vào các mục tiêu có liên quan

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ả khung con ngoài quy trình hoặc trình chạy liên kết.

Kể từ Chrome 125, API browser.debugger hỗ trợ các phiên phẳng. Điều này cho phép bạn thêm các mục tiêu bổ sung dưới dạng phần tử con vào phiên trình gỡ lỗi chính và nhắn tin cho các mục tiêu đó mà không cần gọi thêm một lệnh gọi khác đến browser.debugger.attach. Thay vào đó, bạn có thể thêm thuộc tính sessionId khi gọi browser.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 trình nghe cho sự kiện 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");
  }
});

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 tuỳ chọn flatten được đặt thành true:

await browser.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 các khung mà mục tiêu biết, tức là chỉ giới hạn ở các khung là phần tử con trực tiếp của một khung 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 khác nguồn gốc), việc gọi Target.setAutoAttach cho mục tiêu 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, việc này không mang tính đệ quy, vì vậy, bạn cũng cần gọi Target.setAutoAttach để 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 trình gỡ lỗi từ kho lưu trữ chrome-extension-samples.

Loại

Debuggee

Giá trị nhận dạng của trình 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ã của tiện ích mà bạn định gỡ lỗi. Bạn chỉ có thể đính kèm vào trang nền của tiện ích khi sử dụng nút chuyển dòng lệnh --silent-debugger-extension-api.
tabId

number không bắt buộc

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

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

Mã mờ của mục tiêu gỡ lỗi.

DebuggerSession

Chrome 125 trở lên trình duyệt.* kể từ Chrome 148

Giá trị nhận dạng phiên của trình gỡ lỗi. Bạn phải chỉ định một trong các giá trị tabId, extensionId hoặc targetId. Ngoài ra, bạn có thể cung cấp sessionId (không bắt buộc). Nếu sessionId được chỉ định cho các đối số được gửi từ onEvent, thì tức là sự kiện đến từ một phiên giao thức con trong phiên gỡ lỗi gốc. Nếu sessionId được chỉ định khi truyền đến sendCommand, thì sessionId sẽ nhắm đến 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ã của tiện ích mà bạn định gỡ lỗi. Bạn chỉ có thể đính kèm vào trang nền của tiện ích khi sử dụng nút chuyển dòng lệnh --silent-debugger-extension-api.
sessionId

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

Mã mờ của phiên Giao thức Chrome DevTools. Xác định phiên con trong phiên gốc được xác định bằng tabId, extensionId hoặc targetId.
tabId

number không bắt buộc

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

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

Mã mờ của mục tiêu gỡ lỗi.

DetachReason

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

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

Enum

"target_closed"

"canceled_by_user"

TargetInfo

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

Thuộc tính

đã đính kèm

boolean

Đúng nếu trình gỡ lỗi đã được đính kèm.
extensionId

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

Mã tiện ích, được xác định nếu type = "background_page".
faviconUrl

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

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

chuỗi

Mã mục tiêu.
tabId

number không bắt buộc

Mã thẻ, được xác định nếu type == 'page'.
tiêu đề

chuỗi

Tiêu đề trang đích.
loại

TargetInfoType

Loại mục tiêu.
url

chuỗi

URL mục tiêu.

TargetInfoType

Trình duyệt Chrome 44 trở lên .* kể từ Chrome 148

Loại mục tiêu.

Enum

"page"

"background_page"

"worker"

"other"

Phương thức

attach()

browser.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 trình gỡ lỗi có phiên bản lớn khớp và phiên bản nhỏ 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 browser.* kể từ Chrome 148

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

detach()

browser.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 browser.* kể từ Chrome 148

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

getTargets()

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

Trả về danh sách các mục tiêu gỡ lỗi có sẵn.

Giá trị trả về

Promise<TargetInfo[]>

Chrome 96 trở lên browser.* kể từ Chrome 148

sendCommand()

browser.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. Phải là một trong các phương thức được xác định bằng giao thức gỡ lỗi từ xa.
commandParams

object không bắt buộc

Đối tượng JSON có 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ề

Promise<object | undefined>

Chrome 96 trở lên browser.* kể từ Chrome 148

Nội dung phản hồi. Nếu xảy ra lỗi khi đăng thông báo, thì lời hứa sẽ bị từ chối.

Sự kiện

onDetach

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

Được kích hoạt khi trình duyệt chấm dứt phiên gỡ lỗi cho thẻ. Điều này xảy ra khi thẻ đang đóng hoặc Chrome DevTools đang được gọi cho thẻ đính kèm.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(source: Debuggee, reason: DetachReason) => void
```
- source
  
  Debuggee
- lý do
  
  DetachReason

onEvent

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

Được kích hoạt bất cứ khi nào mục tiêu gỡ lỗi phát hành 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
```
- source
  
  DebuggerSession
- method
  
  chuỗi
- tham số
  
  object không bắt buộc

browser.debugger Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

Quyền

Các quy định hạn chế theo chính sách của doanh nghiệp

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

Mục tiêu

Miền bị hạn chế

Làm việc với khung hình

Đính kèm vào các mục tiêu có liên quan

Ví dụ

Loại

Debuggee

Thuộc tính

DebuggerSession

Thuộc tính

DetachReason

Enum

TargetInfo

Thuộc tính

TargetInfoType

Enum

Phương thức

attach()

Thông số

Giá trị trả về

detach()

Thông số

Giá trị trả về

getTargets()

Giá trị trả về

sendCommand()

Thông số

Giá trị trả về

Sự kiện

onDetach

Thông số

onEvent

Thông số

browser.debugger