断点不触发主因是Xdebug CLI配置未生效：需确认php -m含xdebug、CLI php.ini启用zend_extension及xdebug.mode=debug、client_host/port与IDE匹配，并用php -dxdebug.mode=debug显式启动；本地包须为symlink且autoload映射正确，IDE监听需先于PHP进程启动。
本地包 require 成功但断点不触发？检查 Xdebug CLI 配置是否生效
Composer 调试本质是调试 PHP 进程，而本地包（path 类型）的代码在运行时和主项目一样走 PHP CLI 执行路径。断点不触发，90% 是因为 IDE 没连上 CLI 环境下的 Xdebug。
先确认 PHP CLI 是否真加载了 Xdebug：
- 运行
php -m | grep xdebug，必须有输出；若无，检查 CLI 使用的php.ini（非 Apache 或 FPM 的），确认含zend_extension和xdebug.mode=debug - 确保
xdebug.client_host指向你的 IDE 所在机器（本地开发一般为127.0.0.1），xdebug.client_port与 IDE 监听端口一致（如 PhpStorm 默认9003） - 不要依赖
xdebug.start_with_request=yes—— Composer 命令本身不是 HTTP 请求，必须显式启用：php -dxdebug.mode=debug composer install
IDE 中断点要设在本地包的真实文件路径上（比如 ../my-pkg/src/Helper.php），而非 vendor/my-vendor/my-pkg/src/Helper.php —— 后者只是 symlink，调试器需映射到源路径。
为什么改了本地包代码，运行时还是旧逻辑？验证 symlink 是否真正生效
Path 仓库默认尝试创建符号链接，但失败即静默 fallback 到 copy 模式。此时你改的是源码，运行的是 vendor 里的一份副本，自然断点无效、逻辑不更新。
立即验证方式（Linux/macOS）：
- 执行
readlink vendor/my-vendor/my-pkg，输出应为类似../../my-pkg；若为空或显示普通目录结构，说明 fallback 成 copy - Windows 下用
dir vendormy-vendormy-pkg，看到JUNCTION或SYMLINKD才算成功 - 关键前提：本地包自己的
composer.json必须含"options": {"symlink": true}；主项目的repositories配置里加"options"没用 - Windows 用户务必以管理员身份运行终端；Docker 容器需加
--cap-add=SYS_ADMIN并挂载时用:z或:rw,z标志
类能 new 出来，但 Xdebug 进不去方法内部？autoload 映射与命名空间不匹配
能加载类 ≠ 调试器能定位到源码。Xdebug 断点依赖 IDE 根据命名空间反查物理路径，一旦 autoload 配置错位，IDE 就找不到对应文件。
检查三处对齐：
- 本地包
composer.json中"autoload": {"psr-4": {"MyVendor\MyPackage\": "src/"}}—— 注意末尾反斜杠和双反斜杠转义 - 类文件
src/Calculator.php的namespace MyVendorMyPackage;必须与 autoload 前缀完全一致（大小写、分隔符） - 主项目执行
composer dump-autoload --dev（如有autoload-dev）后，检查vendor/composer/autoload_psr4.php里是否已写入该映射 - 测试命令：
php -r "var_dump(class_exists('MyVendorMyPackageCalculator'));"输出bool(true)且无 warning，才说明 autoload 通路完整
调试时提示 “Connection refused” 或 “timeout”？IDE 监听模式与命令启动顺序错乱
Xdebug 是 client-server 模型：PHP 进程是 client，IDE 是 server。如果 PHP 先启动、IDE 后监听，连接就丢弃了，不会重试。
正确操作链：
- 在 IDE 中点击 “Start Listening for PHP Debug Connections”（PhpStorm）或启用 Xdebug 扩展并设断点（VS Code）
- 再执行带 Xdebug 参数的命令：
php -dxdebug.mode=debug -dxdebug.client_host=127.0.0.1 -dxdebug.client_port=9003 $(which composer) install - 不要用
composer install --no-scripts，否则自定义脚本（含你加断点的方法）根本不会运行 - 若调试的是
post-autoload-dump类脚本，记得加--verbose看是否真正触发，有时因 stability 设置被跳过
最易忽略的一点：某些 IDE（如老版本 PhpStorm）在监听开启后，会自动拦截所有 PHP CLI 调试请求——但如果你同时开了多个终端、多个项目，它可能连错进程。建议调试前关闭其他 PHP 调试会话，或在命令中加 -dxdebug.idekey=PHPSTORM 显式绑定。
