Unlocking Chrome Remote Debugging: From the First Bug to V8 Internals

Origin of Debugging

On September 9, 1947, Grace Hopper and her team discovered a moth stuck in a relay of the Mark II computer, causing a failure; after removing it, the machine worked again. They taped the moth to their log with the note "First actual case of bug being found," marking the first documented software bug and the birth of debugging.

Why Debugging Matters for Front‑End Development

Over the past 69 years, debugging techniques have evolved for both hardware and software. Modern front‑end teams, such as the Taobao front‑end group, use innovative methods to tackle remote page debugging, with Chrome/WebView serving as the primary example.

Debugging Principles

Debugging Methods and Permission Management

Typical browser debugging targets are twofold: Chrome on PC and Chrome on Android (Android 4.4+ WebView, which is Chromium‑based).

Chrome PC Browser

Besides the usual console shortcut (e.g., Option+Command+J on macOS), you can debug one Chrome instance from another by launching Chrome with the remote‑debugging port enabled:

# for mac
sudo /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

Chrome Android Browser

To debug Chrome or WebView on Android, connect the device via USB and forward the debugging port:

adb forward tcp:9222 localabstract:chrome_devtools_remote

Permission Management

Google restricts access to the debugging port: on PC it only accepts requests from 127.0.0.1 or localhost; on Android it only accepts requests from the shell user, meaning debugging must occur over USB, not Wi‑Fi.

Starting a Debug Session

After enabling the port, navigate to http://127.0.0.1:9222/json in a browser. The response lists each debuggable page with two crucial fields: id and webSocketDebuggerUrl. The id uniquely identifies the page, and the WebSocket URL is used by Chrome DevTools to communicate with the target.

Chrome provides several HTTP endpoints for remote control:

# List all debuggable pages
http://127.0.0.1:9222/json
# Get WebView/Blink version
http://127.0.0.1:9222/json/version
# Create a new tab with a URL
http://127.0.0.1:9222/json/new?url=...
# Close a tab by id
http://127.0.0.1:9222/json/close/<id>

The webSocketDebuggerUrl is passed as a query parameter to the DevTools front‑end, e.g.:

http://path_to_your_devtool/devtool.html?ws=127.0.0.1:9222/devtools/page/ebdace60-d482-4340-b622-a6198e7aad6e

How JavaScript Debugging Works

Inside Chrome DevTools, the console shows WebSocket messages. For JavaScript debugging, the most important messages include: {"id":6,"method":"Debugger.enable"} After selecting a script and setting a breakpoint, DevTools sends messages such as:

{"id":23,"method":"Debugger.getScriptSource","params":{"scriptId":"103"}}

{"id":24,"method":"Debugger.setBreakpointByUrl","params":{"lineNumber":2,"url":"https://g.alicdn.com/alilog/wlog/0.2.10/??aplus_wap.js,spm_wap.js,spmact_wap.js","columnNumber":0,"condition":""}}

V8 processes these messages using a dispatch map ( m_dispatchMap) that links method names to handler functions.

// V8 Debugger.cpp snippet
DispatcherImpl::DispatcherImpl(FrontendChannel* frontendChannel, Backend* backend) : DispatcherBase(frontendChannel), m_backend(backend) {
    m_dispatchMap["Debugger.enable"] = &DispatcherImpl::enable;
    m_dispatchMap["Debugger.disable"] = &DispatcherImpl::disable;
    // ... other mappings ...
}

Debugger.enable

void V8Debugger::enable() {
    if (m_enableCount++) return;
    DCHECK(!enabled());
    v8::HandleScope scope(m_isolate);
    v8::Debug::SetDebugEventListener(m_isolate, &V8Debugger::v8DebugEventCallback,
        v8::External::New(m_isolate, this));
    m_debuggerContext.Reset(m_isolate, v8::Debug::GetDebugContext(m_isolate));
    compileDebuggerScript();
}

This call installs a debug event listener ( v8DebugEventCallback) and compiles the built‑in debugger‑script.js, which defines JavaScript‑side functions for breakpoint handling.

Debugger.getScriptSource

When DevTools needs the source of a script, it sends Debugger.getScriptSource with a scriptId. V8 returns the original JavaScript source, allowing the DevTools UI to display it.

Debugger.setBreakpointByUrl

DevTools provides a URL and line number. V8 first checks whether the script for that URL is already known, then creates a BreakpointObject and stores it in a map keyed by the script URL. If the URL changes (e.g., a timestamp is added), the breakpoint may be lost, which explains common warning messages.

for (const auto& script : m_scripts) {
    if (!matches(m_inspector, script.second->sourceURL(), url, isRegex)) continue;
    std::unique_ptr<protocol::Debugger::Location> location = resolveBreakpoint(
        breakpointId, script.first, breakpoint, UserBreakpointSource);
    if (location) (*locations)->addItem(std::move(location));
}
*outBreakpointId = breakpointId;

Internally, V8 calls functions from debugger‑script.js (e.g., setBreakpoint) to register the breakpoint both in the JavaScript context and in the C++ runtime.

Breakpoint Hit

When the JavaScript engine executes machine code that contains a breakpoint, the embedded callback triggers the previously installed DebugEventListener. V8 then sends a pause event with the line number back to Chrome DevTools, completing the breakpoint cycle.

Conclusion

Browser debugging ultimately relies on the rendering engine and the JavaScript engine. For JavaScript, the challenge lies in how V8 marks a line and sets a breakpoint, which requires understanding V8’s internal debugging infrastructure.