AWS EC2上PHP调试失败主因是SSH密钥权限（需chmod 600）、路径映射严格一致、Xdebug客户端地址匹配本机IP三者不统一，导致断点不触发或代码未同步。
能连上不代表能用——AWS EC2 上的 PHP 解释器和代码同步必须分开配，且 SSH 密钥权限、路径映射、Xdebug 客户端地址三者不一致，90% 的“连上了但断点不触发”“改了代码没生效”都出在这儿。
SSH 连接失败或 Authentication failed
根本不是服务器没开 SSH，而是 PhpStorm 启动的 SSH 子进程拿不到你的私钥。尤其在 macOS/Linux 下：
- 密钥必须是
chmod 600，比如chmod 600 ~/.ssh/aws-key.pem，否则 OpenSSH 直接拒绝加载 - 不能依赖系统 ssh-agent；PhpStorm 的 SSH 配置页里必须手动点
Auth type > Key pair，再显式指定私钥绝对路径（别填~，写成/Users/you/.ssh/aws-key.pem） - 如果密钥带密码，PhpStorm 只在首次配置时弹窗输入；输错一次后不会重试，直接报错，必须删掉整个 SSH 配置重来
- AWS 安全组要放行端口
22（SFTP/SSH），且 EC2 实例的sshd_config中确认PasswordAuthentication no时，PubkeyAuthentication yes已启用
PHP 解释器识别成功但 Composer/Xdebug 不工作
PhpStorm 只读取你填的 PHP 解释器路径（如 /usr/bin/php），其余工具路径默认为空，不会自动推导。
- Composer 路径必须单独设：进入
Settings > PHP > Composer，把Path to composer.phar改成远程绝对路径，例如/usr/local/bin/composer（不是本地路径，也不是composer命令名） - Xdebug 必须在远程
php.ini中启用：zend_extension=xdebug.so，且关键参数要匹配网络拓扑：
– 如果 PhpStorm 在本机、EC2 是纯远程主机：xdebug.client_host=127.0.0.1不生效，得设为你的本机公网 IP 或内网 IP（查ifconfig）
– 如果用 AWS Cloud9 或本地 WSL 访问 EC2，需确认路由是否经过 NAT，此时常要设xdebug.client_host=host.docker.internal（仅 Docker 场景）或实际网关 IP - 远程 PHP 若由
phpenv、asdf或宝塔管理，务必用完整可执行路径，例如/www/server/php/82/bin/php，不能填php
代码改了但远程没更新（SFTP 同步静默失效）
不是连接断了，是 PhpStorm 没触发上传动作——它只响应「保存」事件，且受映射规则约束。
立即学习“PHP免费学习笔记（深入）”；
- 必须开启
Automatic upload：进Tools > Deployment > Options，勾选Upload changed files automatically to the default server，并选Always（不是On explicit save） - 首次使用前要手动上传一次：右键项目根目录 →
Deployment > Upload to [your-server-name]，否则自动上传逻辑可能未初始化 - 路径映射（Mappings）必须严格一对一：
Local path填你本地项目根（如/Users/you/project），Deployment path必须填 EC2 上对应绝对路径（如/var/www/html），少一个/或多一层./都会导致文件传到错位目录 - 检查
Excluded paths是否误加了vendor/或runtime/——这些目录若被排除，Composer install 后的文件也不会同步过去
远程调试时断点不命中
最常被忽略的是远程 PHP 的源码路径与本地项目路径不一致，Xdebug 找不到对应文件。
- 在
Settings > PHP > Servers中添加服务器条目，Host填 EC2 公网域名或 IP，Port填 Web 服务端口（如80或443），最关键的是勾选Use path mappings，然后手动把远程绝对路径（如/var/www/html）映射到你本地项目根路径 - 确保远程
phpinfo()输出中xdebug.mode是debug（不是off或develop），且xdebug.start_with_request设为yes或触发方式匹配你的调试启动方式（如 Xdebug Helper 浏览器插件） - 如果用 Nginx，确认
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;没被注释或覆盖，否则 Xdebug 收到的文件路径是空或错误的
真正卡住人的地方，从来不是“怎么点那个按钮”，而是密钥权限、路径字符串末尾的斜杠、Xdebug 客户端 IP 是该填 127.0.0.1 还是你的本机局域网 IP ——这些细节不逐项核对，配置看起来全绿，实际运行就静默失败。
