Skip to main content

Debug Frontend Application

Debug Frontend Application

This document provides detailed instructions on how to debug frontend applications in a local environment, including environment configuration, service startup, and cross-origin handling.

Overview

Frontend templates generated in the Application Center need to start an HTTP service locally to provide static file access. To ensure the application can communicate with backend services properly, cross-origin configuration and domain mapping settings are needed.

Configuration Steps

1. Modify Hosts File

To resolve cross-origin issues, you need to add domain mapping to the local hosts file.

macOS:

/etc/hosts

Windows:

C:\Windows\System32\drivers\etc\hosts

Linux:

/etc/hosts

Add the following content at the end of the hosts file:

127.0.0.1 dev.gmssh.com

Note

Modifying the hosts file may require administrator privileges. On macOS you can use the sudo command, on Windows you need to run the editor as administrator.

2. Start Local Service

Open a terminal in the frontend project root directory (same level as index.html), and choose an appropriate method to start the local service based on your development environment.

npx http-server -p 10010 --cors

Parameter Details:

  • -p 10010: Specify service port as 10010
  • --cors: Enable Cross-Origin Resource Sharing (CORS), allowing frontend to call backend APIs
  • -c-1: Disable caching (optional, convenient for development debugging)
  • -o: Auto-open browser (optional)

Full Command Examples:

# Basic startup
npx http-server -p 10010 --cors

# Development mode (disable caching + auto-open browser)
npx http-server -p 10010 --cors -c-1 -o

Method 2: Using VS Code Live Server Plugin

If you use VS Code editor, you can install the Live Server plugin:

  1. Install Plugin: Search "Live Server" in VS Code extension marketplace and install
  2. Configure Port: In VS Code settings, search "liveServer.settings.port", set to 10010
  3. Start Service: Right-click on index.html file, select "Open with Live Server"

Live Server Advantages

  • Hot Reload: Auto-refresh browser after file changes
  • Visual Operation: No need to remember command line parameters
  • Integrated Development: Perfect integration with VS Code

Method 3: Using Other Static Servers

Using serve:

npx serve -s . -l 10010 --cors

Using live-server:

npx live-server --port=10010 --host=127.0.0.1 --cors

Important Reminders

  • Port Consistency: Ensure the startup port matches the port configured in the Application Center
  • CORS Configuration: CORS support must be enabled, otherwise frontend cannot call backend APIs
  • Domain Access: After startup, please use http://dev.gmssh.com:10010 to access, not localhost

Verify Service Startup

After successful service startup, you should see output similar to:

Starting up http-server, serving ./
Available on:
  http://127.0.0.1:10010
  http://dev.gmssh.com:10010
Hit CTRL-C to stop the server

Visit http://dev.gmssh.com:10010 in your browser to verify the service is running properly.

3. Configure Debug Address

Enter in DevTools access address:

http://dev.gmssh.com:10010

After configuration, you can debug your frontend application normally in the GMSSH platform.

Common Issues

Port Occupied

If port 10010 is occupied, you can switch to another port:

npx http-server -p 8080 --cors

Remember to also update the port configuration in the Application Center.

Cross-Origin Issues

Ensure:

  1. Hosts file is configured correctly
  2. Service startup includes --cors parameter
  3. Access address uses configured domain rather than localhost

Hosts File Modification Failed

If you cannot modify the hosts file:

  • macOS/Linux: Use sudo vim /etc/hosts or sudo nano /etc/hosts
  • Windows: Run Notepad as administrator, then open the hosts file

Service Startup Failed

Common causes and solutions:

  • Node.js Not Installed: Visit nodejs.org to download and install
  • Network Issues: Use domestic mirror npx http-server -p 10010 --cors --registry=https://registry.npmmirror.com
  • Permission Issues: Ensure you have read/write permission in the project directory

Advanced Configuration

Custom Service Configuration

You can create a configuration file to customize service behavior:

Create server.json configuration file:

{
  "port": 10010,
  "host": "0.0.0.0",
  "cors": true,
  "cache": 3600,
  "showDir": false,
  "autoIndex": true
}

Start with configuration file:

npx http-server -c-1 --cors -p 10010

Using Other Static Servers

Besides http-server, you can also use other tools:

Using serve:

npx serve -s . -l 10010 --cors

Using live-server (supports hot reload):

npx live-server --port=10010 --host=0.0.0.0 --cors

Debugging Tips

Common Debug Commands

Check port occupation:

# macOS/Linux
lsof -i :10010

# Windows
netstat -ano | findstr :10010

Test domain resolution:

ping dev.gmssh.com

Check service status:

curl -I http://dev.gmssh.com:10010

Security Notes

Security Warning

The following configurations are for development environment only, do not use in production:

  1. Only modify hosts file during development, restore it promptly after debugging
  2. Local service should only bind to 127.0.0.1, avoid exposure to public network
  3. Close the service promptly after debugging, avoid long-term port occupation
  4. Do not hardcode debug domain in production code
Copyright © 2026 gmssh团队