Vagrant和Docker在PhpStorm中同步本质不同：Vagrant依赖宿主机与虚拟机间rsync/NFS共享，Docker依赖docker-compose.yml的volumes映射；两者均不走SFTP上传，否则破坏路径一致性、导致Xdebug断点失效或Composer报错。
直接说结论：Vagrant 和 Docker 在 PhpStorm 中的“同步”本质不同——Vagrant 依赖宿主机与虚拟机间的文件夹共享（rsync/NFS），而 Docker 依赖 docker-compose.yml 中的 volumes 映射；两者都**不走 SFTP 自动上传**，强行配 SFTP 反而会破坏路径一致性、导致 Xdebug 断点失效或 Composer 报错。
为什么不能用 SFTP 同步 Vagrant/Docker 项目
PhpStorm 的 SFTP 部署是单向、静默、无状态的文件复制，和 Vagrant/Docker 的实时挂载机制冲突：
- 修改本地文件后 SFTP 上传，但容器/Vagrant 内 PHP 进程可能仍缓存旧文件（尤其启用了 OPCache）
-
vendor/或cache/目录被 SFTP 覆盖后权限错乱，composer install在容器内执行失败 - Xdebug 路径映射基于
volumes或rsync挂载点，SFTP 上传的文件物理路径不一致，触发Cannot resolve path mapping - Vagrant 的
rsync默认只同步Vagrantfile所在目录，若 SFTP 目标路径与之不重合，文件根本不在虚拟机里
正确配置 Vagrant 文件同步：优先用 rsync，慎用 vboxsf
Vagrant 默认用 VirtualBox 的 vboxsf 共享，但性能差、权限怪、符号链接失效。生产级开发应切到 rsync：
- 在
Vagrantfile中添加：config.vm.synced_folder ".", "/vagrant", type: "rsync", rsync__args: ["--verbose", "--delete", "--exclude=.git", "--exclude=node_modules"] - 确保宿主机安装 rsync（macOS 用
brew install rsync，Windows 用 Git Bash 自带） - 每次改完代码，手动运行
vagrant rsync（或启用config.vm.synced_folder ".", "/vagrant", type: "rsync_auto"自动监听） - 别在 PhpStorm 中勾选 “Upload external changes”，它和
rsync_auto冲突，会导致重复同步
Docker 的 volume 映射必须和 PhpStorm 项目根路径严格一致
PhpStorm 通过 docker-compose.yml 启动服务时，所有路径解析（Xdebug、CLI、自动补全）都依赖 volumes 的第一项映射：
立即学习“PHP免费学习笔记（深入）”；
- 确认
docker-compose.yml中 PHP 服务的卷映射形如：volumes: - ".:/var/www/html"（注意开头的.，不是./src或绝对路径） - PhpStorm 的 Remote Interpreter 配置中，“Project path in container” 必须填
/var/www/html，不能少斜杠或多一级 - 如果项目实际在子目录（如
./app/），则volumes改为- "./app:/var/www/html"，且 PhpStorm 项目打开路径也得是./app目录 - Mac 上用
docker.for.mac.host.internal，Win/Linux 用host.docker.internal——写错一个字符，Xdebug 就连不上
调试时最易忽略的路径映射细节
断点不生效？90% 是因为 PhpStorm 的 Servers 配置没对齐容器/Vagrant 内的实际 Web 根路径：
- 进入
Settings > PHP > Servers，Name 填任意，Host 填localhost，Port 填容器/Vagrant 内 Web 服务监听端口（如 Nginx 的 80） - “Absolute path on the server” 必须和
volumes或rsync目标路径完全一致，例如/var/www/html；若 Web 服务器 DocumentRoot 是/var/www/html/public，这里就得填后者 - 不要信 “Auto-detect” —— 它常把
/vagrant当成根，而实际 Web 访问的是/var/www/html - 改完立刻点右下角 “Apply”，否则 Debug 面板里的映射不会更新
