PhpStorm无法连接Docker容器内Xdebug的问题求助

Hey there! Let's work through this tricky debugging setup step by step—these three tools play well together, but it's easy to miss a small config detail that breaks everything. Here are the most common fixes to check:

1. Verify Xdebug is Running & Configured Correctly in the Container #

First, make sure Xdebug is actually active in your PHP container and has the right settings:

• SSH into your container with docker exec -it [your-container-name] bash
• Run php -v—you should see Xdebug listed in the output (if not, your Docker build might have failed to install it properly)
• Run php -i | grep xdebug to check key configs:
  • Ensure xdebug.mode is set to debug (not just develop or disabled)
  • xdebug.client_host should be host.docker.internal (for Mac/Windows Docker Desktop) or your host machine's local IP (for Linux)
  • xdebug.client_port should match what you have in PhpStorm (default is 9003 for Xdebug 3; 9000 for older versions)
  • xdebug.start_with_request should be yes or triggered (if using the Xdebug helper extension)

2. Double-Check PhpStorm's Debug Listening Settings #

• Make sure the "Start Listening for PHP Debug Connections" button (the little phone icon in the top toolbar) is toggled on
• Go to Settings > PHP > Debug > Xdebug:
  • Confirm the "Debug port" matches your container's xdebug.client_port
  • Check the box for "Can accept external connections"
• Go to Settings > PHP > Servers:
  • Create a server entry where the "Host" matches the URL you're using to access your app (e.g., localhost or your custom domain)
  • Critical: Set the "Absolute path on the server" to the exact path of your project root inside the container (e.g., /var/www/html). This path mapping is the #1 cause of missed breakpoints!

3. Validate Your Xdebug Helper Setup #

• Ensure the Chrome Xdebug Helper extension is set to Debug mode (green icon in the toolbar)
• Check that the IDE Key in the extension's settings matches PhpStorm's default (PHPSTORM)
• In Chrome's DevTools (F12), go to Application > Cookies > [your app's domain]—you should see a cookie named XDEBUG_SESSION with the value PHPSTORM (this tells Xdebug to trigger a debug session)

4. Test with a Simple Debug Script #

Create a basic debug-test.php file in your project root:

<?php
xdebug_info();
$testVar = "Hello Xdebug!";
// Set a breakpoint on the line below
echo $testVar;
?>

• Access this file in your browser and check the xdebug_info() output:
  • Look for the "Client" section—if it says "Connected to client: Yes", Xdebug is reaching PhpStorm; if not, there's a network issue
  • Verify the client host/port matches your PhpStorm setup

5. Check PhpStorm's Debug Logs #

If nothing else works, dig into PhpStorm's logs to find errors:

• Go to Help > Show Log in Finder (Mac) or Help > Show Log in Explorer (Windows)
• Open the idea.log file and search for "xdebug"—look for lines like "Connection refused" or "Failed to connect to client", which will point to network or port issues

Try these steps in order, and let me know which part you run into trouble with—I can help narrow it down further!

内容的提问来源于stack exchange，提问作者iphoneintosh