Debugging Packaged Electron Apps | Main Process/Renderer Process Debugging Tips | ASAR File Modification Tutorial

Even after an Electron application has been packaged and distributed, it’s still possible to debug it using various methods. Below is a detailed guide to debugging packaged Electron apps, including command-line debugging, ASAR file modification, and other practical techniques.

I. Debugging by Directly Launching the Packaged Application

Even packaged Electron applications can be debugged using command-line parameters without modifying the application itself.

1. Debugging the Renderer Process

Locate the executable file path of your packaged application and launch it from the command line with debugging parameters:

bash

# Windows example
your-electron-app.exe --remote-debugging-port=8888

# macOS example
/Applications/YourApp.app/Contents/MacOS/YourApp --remote-debugging-port=8888

# Linux example
./your-electron-app --remote-debugging-port=8888

After launching, open a browser and visit the following address to debug the renderer process:

http://127.0.0.1:8888

2. Debugging the Main Process

To debug the main process of a packaged application, use the --inspect parameter:

bash

# Main process debugging
your-electron-app --inspect=8888

Then open Chrome browser and navigate to chrome://inspect, configure the corresponding port (localhost:8888), and you’ll find the main process in the Remote Target list for debugging.

3. Resolving Debugging Connection Issues

When encountering the WebSockets request was expected error:

1. Open Chrome browser and visit chrome://inspect
2. Click the “Configure” button and add localhost:8888
3. Refresh the page and select your application in the “Remote Target” section
4. Click “inspect” to open the debugging tools

II. Debugging Packaged Applications by Modifying ASAR Files

For more in-depth debugging or code modification of packaged applications, you can extract and repackage ASAR files.

1. Preparation

Ensure you have Node.js installed, then install the asar tool globally:

bash

npm install -g asar

2. Locate the ASAR File

In packaged Electron applications, code is typically stored in these locations:

• Windows: your-app/resources/app.asar
• macOS: YourApp.app/Contents/Resources/app.asar
• Linux: your-app/resources/app.asar

3. Extracting the ASAR File

Copy the app.asar file to a safe location, then extract it:

bash

# Command line extraction
asar extract app.asar ./unpacked-app

Or extract using Node.js code:

const asar = require('asar');
asar.extractAll('app.asar', './unpacked-app');

4. Adding Debugging Tools

After extraction, modify the index.html or other entry HTML files to add debugging consoles:

Method 1: Using Eruda (Recommended)

<script src="https://cdn.jsdelivr.net/npm/eruda"></script>
<script>eruda.init();</script>

Method 2: Using VConsole

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/vconsole.min.js"></script>
<script>const vConsole = new VConsole();</script>

5. Modifying Main Process Code to Enable Debugging

Find the main process code (usually main.js or background.js) and add code to open developer tools after window creation:

// Find the window creation code
const mainWindow = new BrowserWindow({// Window configuration});

// Add the following code
mainWindow.webContents.openDevTools({mode: 'undocked'});

6. Repackaging and Replacement

After making modifications, repackage into an ASAR file:

bash

asar pack ./unpacked-app app.asar

Replace the original app.asar file in the program directory with the newly generated one, then restart the application to see the debugging tools.

III. Troubleshooting Common Issues

1. Permission Issues: On macOS and Linux, modifying application files may require administrator privileges – use the sudo command
2. Signature Verification: Some applications have signature verification and may fail to run after modification – try launching with the --no-sandbox parameter
3. Debugging Tools Not Showing: Ensure network connectivity to access CDN resources, or download debugging tools locally and reference them

IV. FAQ: Common Electron Debugging Questions

1. Can packaged Electron applications be debugged?

Yes, packaged Electron applications can be debugged using command-line parameters or by modifying ASAR files, without needing to recompile source code.

2. What’s the difference between debugging Electron’s main process and renderer process?

• Renderer process debugging uses the --remote-debugging-port parameter and focuses on debugging pages and frontend-related code
• Main process debugging uses the --inspect parameter and is used for debugging Electron’s main process logic and window management functions

3. Why do I get a WebSockets error when accessing the debug page?

This occurs because Chrome’s debugging protocol requires WebSocket connections. The solution is to configure and discover debugging targets through the chrome://inspect page rather than directly accessing the IP and port.

4. What should I do if the application won’t run after modifying the ASAR file?

This may be due to permission issues or application signature verification. Try:

• Running the application with administrator privileges
• Checking that the ASAR packaging was completed successfully
• Trying to launch with the --no-sandbox parameter

5. Which is better for Electron debugging: Eruda or VConsole?

Eruda offers more comprehensive functionality, including element inspection and network monitoring, making it more suitable for Electron desktop application debugging. VConsole is more lightweight and better for simple log viewing and basic debugging.

6. How can I debug an Electron application without access to its source code?

You can enable debug mode using command-line parameters, or extract the ASAR file to view and modify code, then add debugging tools and repackage to achieve source-code-free debugging.

With these methods, even packaged and distributed Electron applications can be effectively debugged and analyzed, making them suitable for troubleshooting, feature analysis, and secondary development scenarios.