本文翻譯自：chrome-remote-interface
原文更新時間：July 21,2017
譯者：Pandorym
Chrome 調試協議 的接口，他提供一個使用 JavaScript API 的簡單的命令和通知抽象，幫助使用 Chrome（或任何其他合適的實現）。
這個模塊是眾多 第三方協議客戶端 之一。
簡單的 API 用法
下列片段加載https://github.com，并轉儲每個請求：
const CDP = require('chrome-remote-interface');
CDP((client) => {
// extract domains
const {Network, Page} = client;
// setup handlers
Network.requestWillBeSent((params) => {
console.log(params.request.url);
});
Page.loadEventFired(() => {
client.close();
});
// enable events then start!
Promise.all([
Network.enable(),
Page.enable()
]).then(() => {
return Page.navigate({url: 'https://github.com'});
}).catch((err) => {
console.error(err);
client.close();
});
}).on('error', (err) => {
// cannot connect to the remote endpoint
console.error(err);
});
在 維基 中尋找更多的例子，特別注意，上面的例子可以改寫成 async / await 原型。
你可能還想查看 FAQ。
安裝
npm install chrome-remote-interface
全局安裝（-g）可以使用附隨的客戶端。
實現
這個模塊應該和每個實現了 Chrome 調試協議 的應用程序一起工作。特別是，它已經對以下實現進行了測試：
| Implementation | Protocol version | Protocol | List | New | Activate | Close | Version |
|---|---|---|---|---|---|---|---|
| Google Chrome | tip-of-tree | yes | yes | yes | yes | yes | yes |
| Microsoft Edge | partial | yes | yes | no | no | no | yes |
| Node.js (v6.3.0+) | node | yes | no | no | no | no | yes |
| Safari (iOS) | partial | no | yes | no | no | no | no |
目標（target）的含義根據實現而差異，例如，每個 Chrome 標籤代表一個目標，而對於 Node.js 一個目標是當前視察的腳本。
設置
為了使用這個模塊，Chrome 自身或其他實現的實例 需要運行在一個已知端口（默認為localhost:9222）。
Choreme/Chromium
Desktop
啟動 Chrome 時，使用--remote-debugging-port選項，例如：
google-chrome --remote-debugging-port=9222
Headless
在 59 之後的版本，額外使用--headless選項，例如：
google-chrome --headless --remote-debugging-port=9222
Android
插入設備，并啟動 端口轉發， 例如：
adb forward tcp:9222 localabstract:chrome_devtools_remote
WebView
為了視察，WebView 必需 已配置調試，並且對應的進程 ID 必需是已知的。有幾種方法可以獲得它，例如：
adb shell grep -a webview_devtools_remote /proc/net/unix
最後，可以使用如下方式啟動端口轉發：
adb forward tcp:9222 localabstract:webview_devtools_remote_<pid>
Edge
安裝并運行 Edge 診斷配適器（Diagnostics Adapter）。
Node.js
啟動 Node.js 使附加--inspect選項，例如：
node --inspect=9222 script.js
Safari (iOS)
安裝并運行 iOS WebKit 調試代理（Debug Proxy）。
附隨的客戶端
這個模塊有一個附隨的客戶端應用程序，他可用於交互式的控制遠程實例。
目標管理
該附隨的客戶端提供用於與 HTTP 前端交互的子命令（例如，List、New 等）,運行--help以顯示一個可用選項的列表。
下面是一些例子：
$ chrome-remote-interface new 'http://example.com'
{
"description": "",
"devtoolsFrontendUrl": "/devtools/inspector.html?ws=localhost:9222/devtools/page/b049bb56-de7d-424c-a331-6ae44cf7ae01",
"id": "b049bb56-de7d-424c-a331-6ae44cf7ae01",
"thumbnailUrl": "/thumb/b049bb56-de7d-424c-a331-6ae44cf7ae01",
"title": "",
"type": "page",
"url": "http://example.com/",
"webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/b049bb56-de7d-424c-a331-6ae44cf7ae01"
}
$ chrome-remote-interface close 'b049bb56-de7d-424c-a331-6ae44cf7ae01'
查閱
使用子命令inspect可以以 REPL 方式進行 命令執行 和 事件綁定。不像常規的 API，該回調被重寫了，以方便顯示命令的返回值和事件的信息。還有，這里的事件綁定是簡化的，執行一個速寫方法（例如Page.loadEventFired()）切換事件註冊。
記住，該 REPL 接口提供了實現。
這是一個簡單的片段：
$ chrome-remote-interface inspect
>>> Runtime.evaluate({expression: 'window.location.toString()'})
{ result:
{ result:
{ type: 'string',
value: 'https://www.google.it/_/chrome/newtab?espv=2&ie=UTF-8' },
wasThrown: false } }
>>> Page.enable()
{ result: {} }
>>> Page.loadEventFired() // registered
{ 'Page.loadEventFired': true }
>>> Page.loadEventFired() // unregistered
{ 'Page.loadEventFired': false }
>>> Page.loadEventFired() // registered
{ 'Page.loadEventFired': true }
>>> Page.navigate({url: 'https://github.com'})
{ result: { frameId: '28677.1' } }
{ 'Page.loadEventFired': { timestamp: 21385.383076 } }
>>> Runtime.evaluate({expression: 'window.location.toString()'})
{ result:
{ result: { type: 'string', value: 'https://github.com/' },
wasThrown: false } }
事件過濾
為了減少來自事件監聽器的數據顯示量，可以提供一個過濾函數。在這個例子中，只顯示資源的 URL：
$ chrome-remote-interface inspect
>>> Network.enable()
{ result: {} }
>>> Network.requestWillBeSent(params => params.request.url)
{ 'Network.requestWillBeSent': 'params => params.request.url' }
>>> Page.navigate({url: 'https://www.wikipedia.org'})
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/' }
{ result: { frameId: '5530.1' } }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia_wordmark.png' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/img/Wikipedia-logo-v2.png' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/js/index-3b68787aa6.js' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/js/gt-ie9-c84bf66d33.js' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/img/sprite-bookshelf_icons.png?16ed124e8ca7c5ce9d463e8f99b2064427366360' }
{ 'Network.requestWillBeSent': 'https://www.wikipedia.org/portal/wikipedia.org/assets/img/sprite-project-logos.png?9afc01c5efe0a8fb6512c776955e2ad3eb48fbca' }
內置文檔
在 REPL和常規 API 中的每個協議對象都擁有在元信息中找到的描述符。此外，還添加了一個category字段，譯確定成員是command、event或type。
例如，學習如何調用Page.navigate：
>>> Page.navigate
{ [Function]
category: 'command',
parameters: { url: { type: 'string', description: 'URL to navigate the page to.' } },
returns:
[ { name: 'frameId',
'$ref': 'FrameId',
hidden: true,
description: 'Frame id that will be navigated.' } ],
description: 'Navigates current page to the given URL.',
handlers: [ 'browser', 'renderer' ] }
學習來自Network.requestWillBeSent事件的參數：
>>> Network.requestWillBeSent
{ [Function]
category: 'event',
description: 'Fired when page is about to send HTTP request.',
parameters:
{ requestId: { '$ref': 'RequestId', description: 'Request identifier.' },
frameId:
{ '$ref': 'Page.FrameId',
description: 'Frame identifier.',
hidden: true },
loaderId: { '$ref': 'LoaderId', description: 'Loader identifier.' },
documentURL:
{ type: 'string',
description: 'URL of the document this request is loaded for.' },
request: { '$ref': 'Request', description: 'Request data.' },
timestamp: { '$ref': 'Timestamp', description: 'Timestamp.' },
wallTime:
{ '$ref': 'Timestamp',
hidden: true,
description: 'UTC Timestamp.' },
initiator: { '$ref': 'Initiator', description: 'Request initiator.' },
redirectResponse:
{ optional: true,
'$ref': 'Response',
description: 'Redirect response data.' },
type:
{ '$ref': 'Page.ResourceType',
optional: true,
hidden: true,
description: 'Type of this resource.' } } }
視察Network.Request類型（注意，不同於命令和時間，類型使用大駝峰拼寫法）：
>>> Network.Request
{ category: 'type',
id: 'Request',
type: 'object',
description: 'HTTP request data.',
properties:
{ url: { type: 'string', description: 'Request URL.' },
method: { type: 'string', description: 'HTTP request method.' },
headers: { '$ref': 'Headers', description: 'HTTP request headers.' },
postData:
{ type: 'string',
optional: true,
description: 'HTTP POST request data.' },
mixedContentType:
{ optional: true,
type: 'string',
enum: [Object],
description: 'The mixed content status of the request, as defined in http://www.w3.org/TR/mixed-content/' },
initialPriority:
{ '$ref': 'ResourcePriority',
description: 'Priority of the resource request at the time request is sent.' } } }
Chrome 調試協議版本
chrome-remote-interface默認使用本地版本的協議描述符。不停的更新這個文件，使用scripts/update-protocol.sh並且推送到這個倉庫。
這種行為可以改變在 connection 的remote選項為true，在這種情況，遠程實例要求自己提供協議描述符。
Chrome < 60.0.3097.0 不支持這麼做，所以當這種情況，將從源倉庫獲取協議描述符。
有三個選項可以覆蓋上述行為：
使用特定的協議描述符 connection (
protocol選項)；用原始版本的命令和事件接口來使用前沿特性，這不會出現在 本地版本 的協議描述符；
更新
scripts/update-protocol.sh的本地副本（當使用npm install獲取時不存在）。
瀏覽器用法
這個模塊可以運行在 Web 上下文，但有明顯的局限性，即外部 HTTP請求（List,New 等）不能直接執行，因此為了使用它 用戶必須提供一個全局 criRequest：
function criRequest(options, callback) {}
options與在 Node.js http模塊中的寫法一樣，並且callback是一個接受兩個參數的函數：err（JavaScript Error對象，或null）和data（字符串返回值）。
使用 webpack
只需要使用這個模塊，他就會工作：
const CDP = require('chrome-remote-interface');
使用 non-minified 版本手動運行 webpack ：
DEBUG=true npm run webpack
使用 Vanilla JavaScript
生成一個 JavaScript 文件，這可以使用 <script> 標籤。
在根目錄運行
npm install；-
手動運行 webpack：
TARGET=var npm run webpack TARGET=var DEBUG=true npm run webpack -
像這樣使用：
<script> function criRequest(options, callback) { /*...*/ } </script> <script src="chrome-remote-interface.js"></script>
API
該 API 由三部分組成：
DevTools 方法（對於那些 實現 的支持，例如，List、New 等）；
建立連接；
該實際上的協議接口；
CDP([options], [callback])
使用 Chrome 調試協議 連接一個遠程實例。options是一個對象，并有下列可選屬性：
host：HTTP 前端主機。默認為localhost；port：HTTP 前端端口。默認為9222；secure：HTTPS/WSS 前端。默認為false；-
target：確定這個客戶端應該連接到哪個目標。行為根據類型的變化而變化：一個
function，該函數以List方法返回的數組作為參數，并返回一個目標、或目標在數組中的數值索引；一個目標
object，如New或List方法的返回值；一個
string，他表示原始 WebSocket URL，在這種情況，host和port不用於獲取目標列表，但是他們將用於使相對 URL 變得完整。一個
string，他表示目標 id。
默認是一個實現了返回第一個可用目標的函數。（注意，最多可在同一目標上建立一個連接）；
protocol：Chrome 調試協議 描述符對象。默認使用根據遠程選項選擇的協議；remote：一個布爾值，指示協議是否必須遠程獲取，或者必須使用本地版本。如果設置了protocol選項，這個選擇不會生效。默認值為false。
這些選項在該CDP類實例的所有操作都是有效屬性。除此之外， webSocketURL字段包含當前使用的 WebSocket URL。
callback是一個監聽器，將自動添加到返回EventEmitter的connect事件。當callback缺省時，將返回一個Promise對象，如果觸發connect事件即為成功（fulfilled），如果觸發error事件即為失敗（rejected）。
該EventEmitter支持下列事件：
Event: 'connetn'
function (client) {}
當到 WebSocket 的連接已建立時觸發。
client是一個CDP類的實例。
Event: 'error'
function (err) {}
當不能訪問http://host:port/json，或不能連接到 WebSocket 時觸發。
err是一個Error的實例。
CDP.Protocol([options], [callback])
取得該 Chrome 調試協議 描述符。
options是一個對象，并有下列可選屬性：
host：HTTP 前端主機。默認為localhost；port：HTTP 前端端口。默認為9222；secure：HTTPS/WSS 前端。默認為false；remote：一個布爾值，指示協議是否必須遠程獲取，或者必須使用本地版本。如果不能完成請求，則使用本地版本。默認值為false。
callback在取得協議后執行，他將獲得下列參數：
err：一個Error對象，指明成功狀態；-
protocol：一個對象，擁有下列屬性：remote：一個布爾值，指明返回的描述符是否是遠程版本（取決于用戶選擇或錯誤）；descriptor：該 Chrome 調試協議 描述符。
當callback缺省時，將返回一個Promise對象。
For example:
const CDP = require('chrome-remote-interface');
CDP.Protocol(function (err, protocol) {
if (!err) {
console.log(JSON.stringify(protocol.descriptor, null, 4));
}
});
CDP.List([options], [callback])
請求遠程實例的打開的可用目標 / 標籤的列表。
options是一個對象，并有下列可選屬性：
host：HTTP 前端主機。默認為localhost；port：HTTP 前端端口。默認為9222；secure：HTTPS/WSS 前端。默認為false；
callback在正確取得列表后執行，他將獲得下列參數：
err：一個Error對象，指明成功狀態；targets：該數組返回`http://host:port/json/list中包含的目標列表。
當callback缺省時，將返回一個Promise對象。
For example:
const CDP = require('chrome-remote-interface');
CDP.List(function (err, targets) {
if (!err) {
console.log(targets);
}
});
CDP.New([options], [callback])
在遠程實例中創建一個新的目標 / 標籤。
options是一個對象，并有下列可選屬性：
host：HTTP 前端主機。默認為localhost；port：HTTP 前端端口。默認為9222；secure：HTTPS/WSS 前端。默認為false；url：URL 用於載入新目標 / 標籤。默認為about:blank。
callback在創建目標后執行，他將獲得下列參數：
err：一個Error對象，指明成功狀態；targets：該對象，來自http://host:port/json/new中包含的目標。
當callback缺省時，將返回一個Promise對象。
For example:
const CDP = require('chrome-remote-interface');
CDP.New(function (err, target) {
if (!err) {
console.log(target);
}
});
CDP.Activate([options], [callback])
在遠程實例中激活一個目標 / 標籤。
options是一個對象，并有下列可選屬性：
host：HTTP 前端主機。默認為localhost；port：HTTP 前端端口。默認為9222；secure：HTTPS/WSS 前端。默認為false；id：目標 id。必填，無默認值。
callback在激活請求收到響應后執行，他將獲得下列參數：
err：一個Error對象，指明成功狀態；
當callback缺省時，將返回一個Promise對象。
For example:
const CDP = require('chrome-remote-interface');
CDP.Activate({'id': 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, function (err) {
if (!err) {
console.log('target is activated');
}
});
CDP.Close([options], [callback])
關閉一個在遠程實例中打開的目標 / 標籤。
options是一個對象，并有下列可選屬性：
host：HTTP 前端主機。默認為localhost；port：HTTP 前端端口。默認為9222；secure：HTTPS/WSS 前端。默認為false；id：目標 id。必填，無默認值。
callback在關閉請求收到響應后執行，他將獲得下列參數：
err：一個Error對象，指明成功狀態；
當callback缺省時，將返回一個Promise對象。
For example:
const CDP = require('chrome-remote-interface');
CDP.Close({'id': 'CC46FBFA-3BDA-493B-B2E4-2BE6EB0D97EC'}, function (err) {
if (!err) {
console.log('target is closing');
}
});
注意，當目標排隊等待刪除時，該回調將被觸發，但真正的刪除將異步執行。
CDP.Version([options], [callback])
從遠程實例請求版本信息。
options是一個對象，并有下列可選屬性：
host：HTTP 前端主機。默認為localhost；port：HTTP 前端端口。默認為9222；secure：HTTPS/WSS 前端。默認為false；
callback在正確獲得版本信息后執行，他將獲得下列參數：
err：一個Error對象，指明成功狀態；info：一個 JSON 對象，來自http://host:port/json/version包含的版本信息。
當callback缺省時，將返回一個Promise對象。
For example:
const CDP = require('chrome-remote-interface');
CDP.Version(function (err, info) {
if (!err) {
console.log(info);
}
});
Class: CDP
Event: 'event'
function (message) {}
當遠程實例通過 WebSocket 發送任何通知時觸發。
message是接收的對象，他有下列屬性：
method：一個字符串，描述該通知（例如）'Network.requestWillBeSent'）；params：一個對象，包含有效載荷（payload）。
參考 Chrome 調試協議 規格獲取更多信息。
For example:
client.on('event', function (message) {
if (message.method === 'Network.requestWillBeSent') {
console.log(message.params);
}
});
Event: '<domain>.<method>'
function (params) {}
當遠程實例通過 WebSocket 發送關於<domain>.<method>的通知時觸發。
params：一個對象，包含有效載荷（payload）。
這是一個實用的時間，他可以很容易的偵聽特定的時間（看 'event'），for example:
client.on('Network.requestWillBeSent', console.log);
Event: 'ready'
function () {}
每次不存在 等待遠程實例響應的命令 時觸發。交互是異步的，序列化命令隊列的唯一方式是使用 send 方法提供的回調。這個時間起到一個屏障作用，並且在某些簡單情況下，可以避免回調地獄。
鼓勵使用者廣泛的檢查每個方法的響應，並且在處理複雜的異步程序流是應該更喜歡 promises API。
例如，僅在啟用了Network和Page域的通知后才加載 URL：
client.Network.enable();
client.Page.enable();
client.once('ready', function () {
client.Page.navigate({'url': 'https://github.com'});
});
在這個特殊的情況下，不強制序列化執行可能導致遠程實例不能正確的交付通知該客戶端。
Event: 'disconnect'
function () {}
當實例關閉該 WebSocket 連接時觸發。
這可能發生在當用戶打開 DevTools 或關閉標籤。
client.send(method, [params], [callback])
向遠程實例發出一個命令。
method 是一個描述命令的字符串。
params 是一個對象，包含有效載荷。
callback 是在收到遠程實例關於這個命令的響應時執行，他將獲得下列參數：
error：一個布爾值，指明成功狀態，來自遠程實例；response：一個對象，包含響應（result字段，如果error === false）或者錯誤知識（error字段，如果`error === true）。
當callback缺省時，將返回一個Promise對象，並且 fulfilled/rejected 狀態取決于error屬性。
在低等級 WebSocket 錯誤的情況下，該error包含產生的Error對象，並且沒有response返回。
注意，他的字段id在 Chrome 調試協議 中提到是內部管理的，並且不向用戶揭露。
For example:
client.send('Page.navigate', {'url': 'https://github.com'}, console.log);
client.<domain>.<method>([params], [callback])
就是一個速寫：
client.send('<domain>.<method>', params, callback);
For example:
client.Page.navigate({'url': 'https://github.com'}, console.log);
client.<domain>.<event>([callback])
就是一個速寫：
client.on('<domain>.<event>', callback);
唯一的區別是，當callback省卻時，事件只註冊一次，并返回一個Promise對象。
For example:
client.Network.requestWillBeSent(console.log);
client.close([callback])
關閉到遠程實例的連接。
callback當該 WebSocket 成功關閉時執行。
當callback缺省時，將返回一個Promise對象。
FAQ
調用Domain.method，我獲得提示Domain.method is not a function
這意味著你正在使用的協議描述符中不包含Domain.method。如果你確信你的 Chrome 實例支持這種方法，你可以直接調用它：
client.send('Domain.method', ...);
或者詢問 Chrome 正確的協議描述符是什麼：
CDP({remote: true});
看 這裡，獲得更多信息。
調用Domain.method，我獲得提示Domain.method wasn't found
這意味著你正在使用的協議描述符包含一個不受 Chrome 實例支持的方法。最有可能的原因是，你正在嘗試使用一個最前沿的功能，試試升級到新的 Chrome 版本吧。
看 這裡，獲得更多信息。
檢查正確的協議描述符：
$ chrome-remote-interface inspect --remote
Headless Chrome 問題？
記住，--headless Chrome 是相對較新的，他的操作指南（in Chrome）還在制定中。如果你認為遇到了一個 Bug，那麼就看看這些開放性 issues，尤其是 外部 issues。
為什麼當我在 Docker 容器中運行 Chrome 時，我的程序會停滯或表現得出乎意料呢？
這是因為在 Docker 的默認設置中，/dev/shm的大小被設置為 64MB，這可能不足以讓 Chrome 跳轉到某些網頁。
你可以改變這個值，在運行你的容器時附帶說，--shm-size=256m。
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。