目录

Debugging Frontend Pages by Using DevTools

The Web component supports debugging of web frontend pages by using DevTools, a web frontend development and debugging tool that allows you to debug an application's frontend pages on a PC. Before you do this, use setWebDebuggingAccess() to enable frontend page debugging for the Web component and make sure the test device connected to the PC runs 4.1.0 or a later version.

Wireless Debugging

Since API version 20, the wireless debugging API setWebDebuggingAccess20+ can be used to simplify the debugging process.

[h2]Enabling Web Debugging for Application Code

Before debugging a web page, call the setWebDebuggingAccess() API to enable the web debugging feature.

If the web debugging function is not enabled, DevTools cannot detect the web page to be debugged.

  1. To enable the web debugging feature in application code, call the setWebDebuggingAccess20+ API to set the TCP socket port and enable the web debugging feature.

    import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
const DEBUGGING_PORT: number = 8888;

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  aboutToAppear(): void {
    try {
      // Enable wireless web debugging and specify the TCP socket port.
      webview.WebviewController.setWebDebuggingAccess(true, DEBUGGING_PORT);
    } catch (error) {
      console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
    }
  }

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

    Port 8888 used in the sample code is for reference only. You must ensure that the port number can be used by applications in practice. If the port cannot be used because the port is occupied or the application does not have the permission to use the port, the API throws an exception or the ArkWeb cannot enable the debugging mode.

  2. To enable the debugging feature, you need to add the following permission to the module.json5 file of the application's HAP in DevEco Studio. For details, see Declaring Permissions in the Configuration File.

     "requestPermissions":[
   {
     "name" : "ohos.permission.INTERNET"
   }
 ]

[h2]Opening the Debugging Tool Page in Chrome

  1. Input chrome://inspect/#devices in the address box of Chrome on the PC and open the page.

  2. Configure the Chrome debugging tool.

    Select Discover network targets to discover the web page to be debugged based on the specified IP address and port number.

    (1) Click the Configure button.

    (2) In Target discovery settings, add the IP address of the device to be debugged and the port specified in the setWebDebuggingAccess20+ API, for example, 192.168.0.3:8888.

The debugging tool and the device to be debugged must be in the same LAN and can access each other. If the device to be debugged has multiple IP addresses, use the IP address that is in the same network segment as the IP address of the debugging tool.

[h2]Waiting for the Page to Be Debugged

If the preceding steps are successful, the Chrome debugging page displays the web page to be debugged.

[h2]Starting Web Page Debugging

USB Debugging

[h2]Enabling Web Debugging for Application Code

Before debugging a web page, call the setWebDebuggingAccess() API to enable the web debugging feature.

If the web debugging function is not enabled, DevTools cannot detect the web page to be debugged.

  1. Enable web frontend page debugging in the application code.

    import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  aboutToAppear() {
    // Enable web frontend page debugging.
    webview.WebviewController.setWebDebuggingAccess(true);
  }

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
    }
  }
}

  2. To enable the debugging feature, you need to add the following permission to the module.json5 file of the application's HAP in DevEco Studio. For details, see Declaring Permissions in the Configuration File.

    "requestPermissions":[
  {
    "name" : "ohos.permission.INTERNET"
  }
]

[h2]Connecting the Device to a PC

Connect the device to a PC and enable Developer mode for subsequent port forwarding operations.

  1. Enable Developer mode and USB debugging on your device.

    (1) Choose Settings > System and check whether Developer options is available. If not, go to Settings > About and touch the version number for seven consecutive times until the message "Enable developer mode?" is displayed. Touch OK and enter the PIN (if set). Then the device will automatically restart.

    (2) Connect the device to the PC using a USB cable. Choose Settings > System > Developer options and enable USB debugging. In the displayed dialog box, touch Allow.

  2. Run the hdc command to connect to the device.

    Run the following command in the CLI to check whether hdc can discover the device.

    hdc list targets

    • If the command returns the device ID, hdc is connected to the device.

    • If the command returns [Empty], hdc has not discovered the device.

  3. Enter the hdc shell.

    After the device is connected, run the following command to enter hdc shell:

    hdc shell

[h2]Port Forwarding

After the application code calls the setWebDebuggingAccess API to enable web debugging, the ArkWeb kernel starts a domain socket listener to enable DevTools to debug web pages.

However, Chrome cannot directly access the domain socket on the device. Therefore, the domain socket on the device needs to be forwarded to the PC.

You are advised to automatically map WebView debugging links.

If the DevEco Studio version is earlier than the required version, perform the following steps:

  1. Run the following command in hdc shell to obtain the domain socket created by ArkWeb on the device.

    cat /proc/net/unix | grep devtools

    • If the preceding steps are correct, the command output shows the domain socket port used for querying.

    • If no result is returned, check again.

      (1) The web debugging switch is enabled for the app.

      (2) The app uses the Web component to load the web page.

  2. Exit hdc shell, and run the following command to forward the obtained domain socket to TCP port 9222 of the PC.

    Run the exit command to exit the hdc shell.

    exit

    Run the following command to forward the port:

    hdc fport tcp:9222 localabstract:webview_devtools_remote_38532

    The number following webview_devtools_remote_ indicates the process ID of the application where the Web component is located. The number is not fixed. Change the number following webview_devtools_remote_ to the obtained value.

    If the process ID of the application changes (for example, the application is restarted), configure port forwarding again.

    The following figure shows a successful command execution:

  3. Run the following command to check whether the port is successfully forwarded.

    hdc fport ls

    • If a port forwarding task is returned, the port is successfully forwarded.

    • If [Empty] is returned, port forwarding fails.

[h2]Script

On Windows

Copy the following information to create a .bat file, enable application debugging, and run the file.

@echo off
setlocal enabledelayedexpansion

:: Initialize port number and PID list
set PORT=9222
set PID_LIST=

:: Get the list of all forwarded ports and PIDs
for /f "tokens=2,5 delims=:_" %%a in ('hdc fport ls') do (
    if %%a gtr !PORT! (
        set PORT=%%a
    )
    for /f "tokens=1 delims= " %%c in ("%%b") do (
        set PID_LIST=!PID_LIST! %%c
    )
)

:: Increment port number for next application
set temp_PORT=!PORT!
set /a temp_PORT+=1
set PORT=!temp_PORT!

:: Get the domain socket name of devtools
for /f "tokens=*" %%a in ('hdc shell "cat /proc/net/unix | grep devtools"') do (
    set SOCKET_NAME=%%a

    :: Extract process ID
    for /f "delims=_ tokens=4" %%b in ("!SOCKET_NAME!") do set PID=%%b

    :: Check if PID already has a mapping
    echo !PID_LIST! | findstr /C:" !PID! " >nul
    if errorlevel 1 (
        :: Add mapping
        hdc fport tcp:!PORT! localabstract:webview_devtools_remote_!PID!
        if errorlevel 1 (
            echo Error: Failed to add mapping.
            pause
            exit /b
        )

        :: Add PID to list and increment port number for next application
        set PID_LIST=!PID_LIST! !PID!
        set temp_PORT=!PORT!
        set /a temp_PORT+=1
        set PORT=!temp_PORT!
    )
)

:: If no process ID was found, prompt the user to open debugging in their application code and provide the documentation link
if "!SOCKET_NAME!"=="" (
    echo No process ID was found. Please open debugging in your application code using the corresponding interface. You can find the relevant documentation at this link: [https://gitcode.com/openharmony/docs/blob/master/en/application-dev/web/web-debugging-with-devtools.md]
    pause
    exit /b
)

:: Check mapping
hdc fport ls

echo.
echo Script executed successfully. Press any key to exit...
pause >nul

:: Try to open the page in Edge
start msedge chrome://inspect/#devices

:: If Edge is not available, then open the page in Chrome
if errorlevel 1 (
    start chrome chrome://inspect/#devices
)

endlocal

On Linux or macOS

Copy the following information to create an .sh file. Note that you need to run the chmod command and convert the file format. Enable the application debugging and run the file.

This script deletes all port forwarding rules first. If other tools (such as DevEco Studio) are also using the port forwarding function, they will be affected.

#!/bin/bash

# Get current fport rule list
CURRENT_FPORT_LIST=$(hdc fport ls)

# Delete the existing fport rule one by one
while IFS= read -r line; do
    # Extract the taskline
    IFS=' ' read -ra parts <<< "$line"
    taskline="${parts[1]} ${parts[2]}"

    # Delete the corresponding fport rule
    echo "Removing forward rule for $taskline"
    hdc fport rm $taskline
    result=$?

    if [ $result -eq 0 ]; then
        echo "Remove forward rule success, taskline:$taskline"
    else
        echo "Failed to remove forward rule, taskline:$taskline"
    fi

done <<< "$CURRENT_FPORT_LIST"

# Initial port number
INITIAL_PORT=9222

# Get the current port number, use initial port number if not set previously
CURRENT_PORT=${PORT:-$INITIAL_PORT}

# Get the list of all PIDs that match the condition
PID_LIST=$(hdc shell cat /proc/net/unix | grep webview_devtools_remote_ | awk -F '_' '{print $NF}')

if [ -z "$PID_LIST" ]; then
    echo "Failed to retrieve PID from the device"
    exit 1
fi

# Increment the port number
PORT=$CURRENT_PORT

# Forward ports for each application one by one
for PID in $PID_LIST; do
    # Increment the port number
    PORT=$((PORT + 1))

    # Execute the hdc fport command
    hdc fport tcp:$PORT localabstract:webview_devtools_remote_$PID

    # Check if the command executed successfully
    if [ $? -ne 0 ]; then
        echo "Failed to execute hdc fport command"
        exit 1
    fi
done

# List all forwarded ports
hdc fport ls

[h2]Opening the Debugging Tool Page in Chrome

  1. Input chrome://inspect/#devices in the address box of Chrome on the PC and open the page.

  2. Configure the Chrome debugging tool.

    The web page to be debugged needs to be discovered from the local TCP port 9222. Therefore, ensure that Discover network targets is selected. Then, configure the network.

    (1) Click the Configure button.

    (2) Add localhost:9222 to Target discovery settings.

  3. To debug multiple applications at the same time, add multiple port numbers in Configure of the Devices option on the Chrome debugging tool page.

[h2]Waiting for the Page to Be Debugged

If the preceding steps are successful, the Chrome debugging page displays the web page to be debugged.

[h2]Starting Web Page Debugging

FAQs

[h2]Can I debug web pages opened in the system browser?

It depends on whether the web debugging feature is enabled for the system browser.

[h2]What should I do if hdc cannot discover devices?

Symptom

The device ID is not displayed after the following command is executed.

hdc list targets

Solution

[h2]What should I do if "unauthorized" is displayed in the hdc command output?

Symptom

When the hdc command is executed, the system displays a message indicating that the device is "unauthorized".

Possible Causes

The PC is not authorized to debug the device.

Solution

When a device with USB debugging enabled is connected to an unauthorized PC, a dialog box is displayed, asking you whether to allow USB debugging. In this case, select Allow.

[h2]What should I do if the domain socket of DevTools cannot be found?

Symptom

  1. After the following command is executed in the hdc shell, no result is returned. 
    cat /proc/net/unix | grep devtools
  2. The error 'Failed to retrieve PID from the device' is reported when the script is run.

Solution

[h2]Failed to Delete the Port Forwarding Task

Symptom

The error 'Failed to remove forward rule, taskline:' is reported when the script is run.

Solution

[h2]What should I do if port forwarding fails?

Symptom

  1. After the following command is executed in the command line, the previously configured forwarding task is not listed. 
    hdc fport ls
  2. The error 'Failed to execute hdc fport command' is reported when the script is run.

Solution

[h2]What should I do if the web page to be debugged cannot be found in Chrome on the PC after port forwarding is successful?

Symptom

The web page to be debugged cannot be found in Chrome on the PC.

Possible Causes

The port forwarding may be invalid due to the following reasons:

Solution

[h2]What should I do if the Chrome browser on the PC cannot find the web page to be debugged after the wireless debugging mode is enabled?

Symptom

After the wireless debugging mode is enabled for ArkWeb, the Chrome on the PC cannot detect the web page to be debugged.

Possible Causes

Solution

[h2]What should I do if the Web component cannot be debugged using DevTools?

Symptom

The web page to be debugged cannot be found in Chrome on the PC.

Possible Causes

Solution

[h2]What should I do if error 404 is reported when DevTools is used for debugging?

Symptom

When a web page is debugged in the Chrome browser on the computer, the error message "HTTP/1.1 404 Not Found" is displayed.

Possible Causes

Solution