This project demonstrates how to debug Go programs running on remote servers from your local development environment. Using the Delve debugger, you can set breakpoints, step through code, and inspect variables in your local IDE (such as VS Code) just like debugging local programs.

• Remote Debugging: Support cross-network debugging of Go programs running on remote servers
• Automation Scripts: Complete compilation, upload, and deployment automation scripts
• Cross-Platform Compilation: Support compiling Go programs for different architectures (such as ARM64)
• VS Code Integration: Pre-configured VS Code debugging environment
• Easy to Use: One-click remote debugging environment setup

• Go 1.20+
• sshpass (for SSH auto-login)
• VS Code (recommended)

• Linux system
• Delve debugger installed
• SSH access permissions
• Runtime environment for target architecture

git clone https://github.com/wmem/go-remote-debug.git
cd go-remote-debug

sudo apt-get install sshpass

brew install sshpass

sudo yum install sshpass

go install github.com/go-delve/delve/cmd/dlv@latest

If your remote server is ARM64 architecture and you can install on local:

# Install with GOARCH
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go install github.com/go-delve/delve/cmd/dlv@latest

# dlv may as follow
file ~/go/bin/linux_arm64/dlv

# Copy to remote server
scp ~/go/bin/linux_arm64/dlv user@remote-server:/usr/local/bin/dlv
ssh user@remote-server "chmod +x /usr/local/bin/dlv"

dlv version

Edit the configuration parameters in the debug.sh file:

REMOTE_HOST="192.168.99.100"         # Remote server IP address
REMOTE_USER="root"                   # Remote server username
REMOTE_PASSWORD="123456"             # Remote server password
REMOTE_DLV_PATH="/usr/local/bin/dlv" # dlv debugger path
REMOTE_DLV_PORT="2345"               # dlv debug port

EXE_ARCH="arm64"                    # Target architecture
EXE_BINARY="test"                   # Compiled binary name
EXE_MAIN_FILE="main.go"             # Main Go file

./debug.sh remote_debug

This will automatically execute the following steps:

1. Compile Go program for target architecture
2. Upload program to remote server
3. Start remote Delve debugger

./debug.sh build_debug

./debug.sh remote_copy

./debug.sh remote_dlv

1. Open the project in VS Code
2. Set breakpoints
3. Press F5 or use the debug panel to start debugging

The project includes a simple example program (main.go) that demonstrates:

• Variable declaration and assignment
• Loop structures
• Delay operations
• Console output

You can set breakpoints at the following locations to test debugging functionality:

• Line 13: First variable breakpoint test
• Line 16: Second variable breakpoint test
• Lines 19-22: Loop breakpoint test

go-remote-debug/
├── main.go              # Example Go program
├── debug.sh             # Automation debug script
├── go.mod               # Go module file
├── README.md            # Project documentation
├── LICENSE              # MIT license
└── .vscode/             # VS Code configuration
    └── settings.json    # Editor settings
    └── launch.json      # Go remote launch settings

[ERROR] sshpass is not installed

Solution: Install sshpass tool

[ERROR] SSH password not configured

Solution: Set correct REMOTE_PASSWORD in debug.sh

Check:

• Network connection is normal
• SSH service is running
• Username and password are correct
• Firewall settings

Check:

• dlv is installed on remote server
• dlv path is correct
• Port is not occupied
• Architecture compatibility (ensure dlv is compiled for correct architecture)

cannot execute binary file: Exec format error

Solution:

• Ensure dlv is compiled for the correct architecture (ARM64/AMD64)
• Recompile dlv using the methods described in installation section

permission denied

Solution:

• Ensure dlv binary has execute permissions: chmod +x /usr/local/bin/dlv
• Check if user has necessary permissions to run debugger

Welcome to submit Issues and Pull Requests to improve this project!

This project is licensed under the MIT License.

If you encounter problems during usage, please:

1. Check the troubleshooting section
2. Submit an Issue describing your problem
3. Provide detailed error information and environment configuration

Note: Please ensure to modify default passwords and security configurations when using in production environments.