HarmonyOS Web Debugging: Master DevTools for Efficient Frontend Debugging

In HarmonyOS application development, debugging frontend pages is a critical step for locating issues and optimizing user experience. DevTools serves as a professional web frontend debugging tool that enables efficient debugging of mobile device frontend pages from a computer. Combined with HarmonyOS 4.1.0 and later devices, it significantly improves developer debugging efficiency.

Pre-Debugging Core Preparation

Before using DevTools to debug frontend pages, two basic preparation tasks must be completed to ensure a smooth debugging process:

Enable Web Debugging Switch : Developers must use the setWebDebuggingAccess() interface to enable the Web component debugging capability. Without this, DevTools cannot identify the page to be debugged.

Configure Permissions : In the DevEco Studio application project hap module's module.json5 file, add the ohos.permission.INTERNET permission to provide network support for debugging functionality.

Two Debugging Methods Practical Guide

1. Wireless Debugging (API Version 20 and Above)

Wireless debugging requires no data cable connection. The core requirement is that the device and computer are on the same LAN and can access each other. Specific steps:

Enable Debugging Switch : In the application code, call setWebDebuggingAccess(true, port) interface, specifying the TCP Socket port.

Configure Chrome Debugging Page :

Open Chrome browser on the computer.

Enter chrome://inspect/#devices.

Check the "Discover network targets" option.

Click the "Configure" button and add the device IP address and debugging port.

Identify and Debug Page : Launch the application to access the Web page. Wait for the Chrome debugging page to recognize the target page, then click the "inspect" button to open the DevTools debugging window for element inspection, code debugging, and other operations.

2. USB Connection Debugging

USB connection debugging offers stronger stability and is suitable for complex debugging scenarios. The operation steps are relatively more involved:

Basic Configuration : Enable the application Web debugging switch, device developer options, and USB debugging function. Connect the device to the computer via USB data cable and allow computer debugging authorization in the device popup.

Confirm Device Connection : Open the computer command line tool and execute hdc list targets. If a device ID is returned, the connection is successful. If [Empty] is returned, recheck device connection and debugging settings.

Port Forwarding Configuration : Enter hdc shell and use the command cat /proc/net/unix | grep devtools to query the ArkWeb corresponding domain socket. Forward it to the computer's TCP 9222 port (example command:

hdc fport tcp:9222 localabstract:webview_devtools_remote_<pid>

). Execute hdc fport ls to confirm forwarding success.

Debugging Page Configuration and Launch :

In Chrome browser, enter chrome://inspect/#devices.

Check "Discover network targets".

Configure localhost:9222.

Wait for target page recognition, then click "inspect" to enter the debugging interface.

3. Convenience Scripts to Improve Efficiency

To simplify port forwarding operations, the official platform provides convenience scripts for corresponding platforms: Windows platform can create a .bat file, Mac/Linux platform can create a .sh file. The script automatically obtains the process ID, configures port forwarding, and opens the Chrome debugging page, greatly reducing manual operation cost. Note that the Mac/Linux platform script clears old hdc forwarding tasks to avoid conflicts with other tools.

Common Issues and Solutions

The technical documentation describes various issues that may arise during debugging. Below are targeted solutions for high-frequency problems to help developers quickly troubleshoot faults:

hdc cannot discover device : Confirm device has developer options and USB debugging enabled, use data cable connection, ensure computer has hdc tool installed.

hdc command shows device "unauthorized" : Check device popup and click to allow computer debugging authorization.

Cannot find DevTools domain socket : Confirm application has enabled Web debugging switch and Web component has successfully loaded the webpage.

Delete port forwarding task fails : Execute hdc kill to terminate hdc service, then execute hdc start to restart service. Execute hdc list targets to confirm device online status; if empty, reconnect device.

Port forwarding unsuccessful : Confirm device domain socket exists, check if computer TCP 9222 port is occupied. If occupied, switch to another free TCP port like 9223, and simultaneously modify the corresponding port number in Chrome browser Target discovery settings.

Port forwarding successful but Chrome cannot discover page : Confirm port not occupied, domain socket exists and process ID matches. Clean up extra forwarding tasks. Visit http://localhost:9222/json (replace with actual TCP port). If page returns content, wait for Chrome debugging page to display target webpage.

Wireless debugging cannot discover device : Confirm device and computer are on the same LAN and network is unobstructed between them.

Web component cannot use DevTools for debugging : If using both HDC and ADB simultaneously, close ADB process first to ensure DevTools establishes WebSocket connection with device.

Debugging shows 404 error : Mostly due to Chrome version incompatibility. Upgrade Chrome to latest version, or manually construct debugging URL for debugging.

DevTools provides an efficient and convenient solution for HarmonyOS frontend page debugging. Wireless debugging is suitable for quick troubleshooting, while USB connection debugging is suitable for complex scenarios. Developers can choose the appropriate method based on actual needs. Mastering debugging steps and common problem solutions can effectively shorten problem location time and improve development efficiency. In subsequent development, convenience scripts can be combined to further optimize the debugging process and fully leverage DevTools debugging capabilities.

For more related technical guidance, visit the HarmonyOS Developer website and follow the path: Guide → Application Framework → ArkWeb → Web Debugging and Maintenance → Using DevTools to Debug Frontend Pages.